---
title: "Local MCP Reference"
description: "Tools, environment variables, and errors for the local Y2 MCP server"
canonical: https://y2.dev/docs/api/mcp-reference/
---

# Local MCP Reference

Tools, environment variables, and errors for the local Y2 MCP server

This reference covers `@y2-intel/mcp` version `0.4.0`. The package is released separately from the platform. Inspect `tools/list`, `resources/list`, and `prompts/list` for your installed version. Follow [local MCP setup](https://y2.dev/docs/api/mcp-local) to connect a client.

## OpenAPI tools

| Tool                       | Purpose                                        | Authorization             |
| -------------------------- | ---------------------------------------------- | ------------------------- |
| `y2_list_api_operations`   | List operation IDs, methods, and paths         | None                      |
| `y2_get_openapi_operation` | Read one operation's parameters and schemas    | None                      |
| `y2_call_api`              | Call an operation using its OpenAPI definition | Operation-specific scopes |

## Typed read tools

| Group                | Count | Resources                                                                                                                                                                   |
| -------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Reports              | 7     | Reports, signals, graphs, text, audio, and transcripts                                                                                                                      |
| News                 | 3     | Items, recaps, and feeds                                                                                                                                                    |
| OSINT                | 18    | Events, country intelligence, maps, feeds, and source status                                                                                                                |
| Intel v2             | 17    | Incidents, entities, graphs, markets, indicators, company financials, cyber-market fusion, signals, cyber, DNS snapshot history, public disclosures, changes, and knowledge |
| Evidence ledger      | 5     | Ledger subjects, point-in-time folds, STIX 2.1 export, sealed records, and seal verification (`ledger:read`)                                                                |
| Account and workflow | 8     | Profiles, webhooks, Projects, Automations, and runs                                                                                                                         |
| Public receipts      | 1     | `y2_get_x402_receipt`                                                                                                                                                       |

Each authenticated call needs the underlying API operation's scope. Use `tools/list` for exact tool names and input schemas.

## Resources and prompts

| Type      | Names                                                                  |
| --------- | ---------------------------------------------------------------------- |
| Resources | `y2://docs/index`, `y2://docs/full`, `y2://openapi`, `y2://quickstart` |
| Prompts   | `integrate-y2-api`, `ask-y2-brief`, `debug-y2-api-call`                |

## Optional action tools

`Y2_MCP_ENABLE_WRITE_TOOLS=true` adds 17 typed write tools and allows write operations through `y2_call_api`:

- Profile create, update, patch, and delete
- Project create and patch
- Automation create, patch, and run
- Webhook create, update, delete, and test
- Subscription delivery update
- Ledger subject open and record append (`ledger:write`)
- Domain DNS lookup (`intel:cyber`), which uses one monthly workspace lookup for each new snapshot

Each tool requires its operation's scope. `Y2_MCP_ENABLE_AGENT=true` adds `y2_ask_agent` and the OpenAI-compatible `y2_create_chat_completion`. Both require `agent:y2`.

Agent Y2 can change resources

Agent Y2 can use tools allowed by the key's scopes and plan. Enable it only when the integration needs those actions.

## Configuration

Prop

Type

Both flags accept `true` or `1`. Restart the client after changing them. Change base URLs only for a Y2-controlled test or development environment.

## Troubleshooting

| Symptom                                                       | Action                                                                                                        |
| ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| Server exits immediately                                      | Check that `node -v` is 24.22.1 or later. Then run `npx -y @y2-intel/mcp@0.4.0` in a terminal and read stderr |
| Client does not show Y2                                       | Confirm that the configuration was saved. Restart the client                                                  |
| `401`                                                         | Check the key for missing, invalid, revoked, or expired credentials                                           |
| `403`                                                         | Check the key's scopes, workspace access, and plan. Edit its scopes if needed                                 |
| `429`, `502`, `503`, or `504`                                 | The server retries twice and honors `Retry-After`. Check the returned error after retries stop                |
| Agent tool is missing                                         | Set `Y2_MCP_ENABLE_AGENT=true`. Restart the client and inspect `tools/list`                                   |
| Typed write tool is missing, or `y2_call_api` rejects a write | Set `Y2_MCP_ENABLE_WRITE_TOOLS=true`. Restart the client and inspect `tools/list`                             |
| Agent credit error                                            | Check the workspace Agent Y2 balance and plan. Agent Y2 does not use x402                                     |
