Connect Y2 through MCP
Configure the local Y2 MCP server for Claude, Codex, and other stdio clients
@y2-intel/mcp connects MCP-compatible clients to Y2 documentation, the OpenAPI contract,
bounded API reads, and Agent Y2. The documented release runs locally over stdio and calls Y2 over
HTTPS.
Separate distribution boundary
The MCP server is a separate public package; its implementation is not in the platform
repository. This page documents the intended integration contract. After installation, treat
MCP tools/list, resources/list, and prompts/list as the source of truth for that installed
package version.
Before you begin
You need:
- Node.js with
npx - An MCP client that supports local stdio servers
- A Y2 API key with only the scopes the client needs
Create a separate key for each MCP client so it can be revoked and audited independently. Keep
Y2_API_KEY in the client environment or its protected configuration; never put it in a prompt or
tool argument.
Configure your client
Add the stdio server from a shell where Y2_API_KEY is set:
codex mcp add y2 --env Y2_API_KEY="$Y2_API_KEY" -- npx -y @y2-intel/mcpConfirm that the configuration exists:
codex mcp listThe command syntax above matches the locally installed Codex CLI. The --env value is saved
with the MCP server configuration, so protect the client configuration file as a secret.
Configure package behavior
The documented package accepts these environment variables:
Prop
Type
Override base URLs only for a Y2-controlled development or test environment. Do not point a credentialed MCP process at an untrusted proxy.
Verify the installed capabilities
Run the MCP Inspector before allowing an agent to call tools:
npx -y @modelcontextprotocol/inspector --cli npx -y @y2-intel/mcp \
--method tools/list
npx -y @modelcontextprotocol/inspector --cli npx -y @y2-intel/mcp \
--method resources/list
npx -y @modelcontextprotocol/inspector --cli npx -y @y2-intel/mcp \
--method prompts/listThe documented release is expected to expose:
| Capability | Name | Y2 authorization |
|---|---|---|
| Resource | y2://docs/index | None |
| Resource | y2://docs/full | None |
| Resource | y2://openapi | None |
| Resource | y2://quickstart | None |
| Tool | y2_get_openapi_operation | None |
| Tool | y2_list_reports | reports:read |
| Tool | y2_get_report | reports:read |
| Tool | y2_list_news | news:read |
| Tool | y2_ask_agent | agent:y2 |
It also documents the prompts integrate-y2-api, ask-y2-brief, and
debug-y2-api-call. If inspection returns a different inventory, follow the schemas returned by
the installed server rather than guessing arguments from this list.
Test a no-key operation first:
npx -y @modelcontextprotocol/inspector --cli npx -y @y2-intel/mcp \
--method tools/call \
--tool-name y2_get_openapi_operation \
--tool-arg operationId=listReportsThen create a scoped key and test one bounded read such as y2_list_reports. Enable
y2_ask_agent only after read-only tools work as expected.
The Agent Y2 scope is not read-only
agent:y2 allows the fixed Y2 agent to use tools available under the key's scopes and plan.
Those tools can change account resources. Omit this scope unless the MCP client is intended to
perform those actions.
Troubleshoot startup
| Symptom | Check |
|---|---|
| Server exits immediately | Run npx -y @y2-intel/mcp in a terminal and inspect stderr |
| No Y2 server in the client | Confirm the client saved the configuration and restart it |
Tool returns 401 | Replace a missing, malformed, revoked, or expired Y2_API_KEY |
Tool returns 403 | Add the required scope to a new key; key scopes are fixed at creation |
Tool returns 429 | Respect Retry-After and the rate-limit headers |
| Agent tool returns a credit error | Check Agent Y2 chat credits and plan access; it does not use x402 |