Connect Y2 through MCP

Y2 Intel offers a hosted, read-only connection for assistants and a local MCP package for developers. Hosted connections let you choose one workspace and approve permissions in Y2 without copying an API key into your assistant.

Connect in Claude or ChatGPT

Use the following URL when your assistant supports adding a custom remote MCP connection:

https://y2-intel-mcp.managed-services.workers.dev/mcp

1. Open your assistant's app or connector settings and add Y2 Intel with the server URL above. Availability of custom connections depends on the assistant and workspace settings; your administrator may need to enable them.
2. Follow the sign-in prompt to Y2. Confirm the client identifier and return destination match the assistant where you started the connection.
3. Choose the Y2 workspace you want to connect. Keep only the requested read permissions you need, then select Allow selected access.
4. Return to your assistant and ask it to check the Y2 connection or list your intelligence profiles. An empty profile list means the selected workspace has no accessible profiles.

You need an existing Y2 account, workspace membership, and connected intelligence access in that workspace. The consent page shows the permissions currently available. Native cards and maps require an assistant that supports MCP Apps; other clients receive structured results and text. A custom connection does not establish a public directory listing or marketplace approval.

What a hosted connection can do

The assistant can display profile cards, signal lists, and maps within the capabilities of its host. Hosted tools do not create or edit profiles, start report generation, send messages, or perform purchases. Each tool checks the approved permissions and your current workspace access. A connection to one workspace cannot read a different workspace.

Try prompts such as:

• “List the Y2 Intel profiles in my connected workspace.”
• “Show the latest report for this profile, with source citations.”
• “Show regional events for this country on a map.”
• “Show recent signals about this entity, with dates and sources.”

Disconnect, reconnect, or change permissions

Open Settings → Connections in Y2 to see your connections, their workspace, permissions, and expiration. Choose Disconnect to stop new access immediately. Connections expire after 30 days. To change a workspace or permissions, disconnect and start a new connection from your assistant. Reconnect if the assistant reports that authorization has expired or been revoked.

Information returned by a tool is shared with your chosen assistant provider under its policies. Disconnecting stops future access; it does not erase copies already received by that provider. Y2 does not send your Y2 password or internal API credential to the assistant. Read the Privacy Policy for processing, retention, and deletion information.

If sign-in finishes but the assistant does not connect, start a fresh connection in the same browser and complete it before the consent request expires. An unavailable permission means your current workspace access does not include that capability. Contact the workspace administrator if expected access is missing. For other connection issues, contact [email protected] with the assistant name and error text; never include tokens or credentials.

Local MCP package

@y2-intel/mcp 0.2.0 gives local stdio agents access to Y2 docs, the live OpenAPI contract, 52 default tools, and optional action tools.

Quickstart

Before you begin

You need Node.js 20 or later and an MCP client with stdio support. Public discovery works without a key. For authenticated tools, create a separate least-privilege key per client and provide it as Y2_API_KEY; never put a key in a prompt or tool argument.

Verify the package without a key

Ask the installed server to load the live OpenAPI document and list its operations:

npx -y @modelcontextprotocol/inspector --cli npx -y @y2-intel/mcp \
  -- \
  --method tools/call \
  --tool-name y2_list_api_operations

This proves that the server starts and can read Y2's live API contract.

Configure your client

codex mcp add y2 --env Y2_API_KEY="$Y2_API_KEY" -- npx -y @y2-intel/mcp

codex mcp list

For public documentation and OpenAPI discovery only, omit Y2_API_KEY.

Verify the installed capabilities

Inspect the tool schemas before allowing authenticated calls:

npx -y @modelcontextprotocol/inspector --cli npx -y @y2-intel/mcp \
  -- \
  --method tools/list

Version 0.2.0 exposes 52 tools by default. Test y2_list_reports before enabling action tools.

Call any Y2 API operation

For any endpoint without a typed MCP tool:

1. Call y2_list_api_operations to discover the endpoint's current operationId.
2. Call y2_call_api with that operationId, its parameters, and an optional JSON body.

For example:

{
  "operationId": "listReports",
  "parameters": {
    "limit": 10
  }
}

y2_call_api builds path, query, header, and JSON body values from the live spec. Authorization follows the selected operation. Use y2_get_openapi_operation to inspect its full schema first.

Tool reference

OpenAPI-driven tools

Typed read tools

Use tools/list for exact names and schemas, and y2_list_api_operations for the current API.

The four resources remain y2://docs/index, y2://docs/full, y2://openapi, and y2://quickstart. The prompts remain integrate-y2-api, ask-y2-brief, and debug-y2-api-call.

Optional action tools

Y2_MCP_ENABLE_WRITE_TOOLS=true adds 14 typed mutations: profile create/update/patch/delete, project create/patch, automation create/patch/run, webhook create/update/delete/test, and subscription delivery update. Each still requires its matching scope.

Y2_MCP_ENABLE_AGENT=true adds y2_ask_agent and requires agent:y2.

Configuration reference

The package accepts these environment variables:

Both feature flags accept true or 1. Override base URLs only for a Y2-controlled development or test environment. Do not point a credentialed MCP process at an untrusted proxy.

Troubleshooting