Skip to main content

MCP Integration

MCP lets Anyy use tools served by external MCP servers and expose selected Anyy capabilities through an MCP server bridge.

This is the main page for MCP setup and day-to-day operation. For the compact field table, see MCP Config Reference. For toolset selection rules, see Toolsets.

What MCP Gives You​

  • External tools: connect to stdio or HTTP MCP servers.
  • Tool exposure control: allow only selected server tools.
  • Toolset routing: each server contributes a mcp-<server> toolset.
  • Resources and prompts: optionally expose MCP resource/prompt utility tools.
  • Server bridge: run anyy mcp serve so an MCP client can talk to Anyy.

MCP is opt-in. A configured server is not automatically model-visible just because it exists in config.yaml.

Quick Start​

Add one server with a narrow include list:

anyy mcp add docs \
  --command npx \
  --enable \
  --include search \
  --activate-toolset \
  --args -y @example/mcp-server

Then check what was saved and whether the runtime can reach it:

anyy mcp list
anyy mcp show docs
anyy mcp test docs

If Anyy gateway is running, config changes go through RPC and can update the runtime. If not, the CLI writes config.yaml; start or restart the gateway before expecting the server to be available in resident sessions.

Exposure Model​

An MCP server must pass three gates before its tools reach a model:

  1. mcp.client.enabled must be true.
  2. The server must be enabled and expose at least one allowed tool or utility.
  3. The matching mcp-<server> toolset must be selected for the turn or included in toolsets.default.

--activate-toolset adds the matching toolset to toolsets.default, but Anyy rejects activation unless the server is enabled and has an include list.

Visible MCP tool names are sanitized:

mcp_<server>_<tool>

For example, server GitHub.Prod and tool issues.search become the toolset mcp-github_prod and tool mcp_github_prod_issues_search. Use original MCP tool names in include and exclude, not the sanitized names.

Config Shape​

The CLI writes MCP config under mcp.client.servers:

mcp:
  client:
    enabled: true
    servers:
      docs:
        enabled: true
        transport: stdio
        command: npx
        args: ["-y", "@example/mcp-server"]
        startup: lazy
        connect_timeout_ms: 5000
        call_timeout_ms: 30000
        tools:
          include: [search]
          exclude: []
          resources: false
          prompts: false
          default_risk: runtime-high
          approval_policy: none
          execution_policy: confirm
          output_visible_chars: 6000
          output_stored_chars: 30000

toolsets:
  default:
    - terminal
    - mcp-docs

When policy fields are omitted, runtime defaults are default_risk: read, approval_policy: none, and execution_policy: direct. The CLI writes a more conservative default for newly added external servers: runtime-high plus confirm.

Transports​

stdio servers launch a local process:

anyy mcp add project_fs \
  --preset filesystem \
  --enable \
  --include read_file,list_directory \
  --activate-toolset \
  -- /absolute/project/path

http servers use a remote URL:

anyy mcp add docs \
  --transport http \
  --url https://mcp.example.com/mcp \
  --header Authorization=secret:mcp/docs/auth_header \
  --enable \
  --include search

Plain HTTP URLs are allowed only for local endpoints. Sensitive env and headers values must use secret:, env:, or file: references; literal: is rejected for secret-bearing MCP fields.

OAuth​

For hosted MCP servers that use OAuth, set --auth oauth and run login:

anyy mcp add linear \
  --transport http \
  --url https://mcp.example.com/mcp \
  --auth oauth \
  --enable \
  --include list_issues,create_issue

anyy mcp login linear

OAuth tokens are stored in the profile's MCP token store. Use anyy mcp login SERVER_ID again when a token expires or the server requires re-authorization.

Tool Filtering​

Prefer allowlists for external systems:

anyy mcp configure github --include list_issues,create_issue --enable

If you hand-edit YAML, use original MCP tool names:

tools:
  include: [list_issues, create_issue]
  prompts: false
  resources: false

An empty include means server-native tools are not exposed. Utility tools for resources and prompts are exposed only when explicitly enabled and supported by the server session.

Resources, Prompts, And Sampling​

Resources and prompts are disabled by default:

tools:
  resources: true
  prompts: true

When enabled and supported by the server, Anyy registers utility tools such as mcp_docs_list_resources, mcp_docs_read_resource, mcp_docs_list_prompts, and mcp_docs_get_prompt.

MCP sampling is disabled unless sampling.enabled is true. When enabled, set positive caps for tokens, timeout, RPM, and tool-loop limit. Use a model_allowlist when a server may request model calls.

Runtime Operations​

Use the MCP CLI before exposing tools broadly:

anyy mcp probe docs
anyy mcp test docs
anyy mcp reload docs
anyy mcp logs docs
anyy mcp status --json

probe and test inspect connectivity and discovered tools. reload reconnects after config changes. logs shows MCP diagnostics with configured secret values redacted.

Anyy As An MCP Server​

Use the bridge when an MCP client needs to talk to Anyy:

anyy mcp serve

The bridge is configured under mcp.server and is disabled by default:

mcp:
  server:
    enabled: false
    transport: stdio
    scopes: [conversations, tasks]
    expose_approvals: false
    expose_tools: false

Only stdio transport is currently supported for the Anyy MCP server bridge. Supported scopes are listed in the config reference.

Safety Notes​

  • Start with one server and a small include list.
  • Do not expose destructive tools until you understand their arguments and effects.
  • Keep filesystem servers rooted to the smallest useful directory.
  • Store secrets through references, not raw YAML values.
  • Use toolsets.default intentionally; an MCP server can be configured but not generally visible.

Troubleshooting​

  • Server is configured but no tools appear: confirm mcp.client.enabled, server enabled, non-empty tools.include, and active mcp-<server> toolset.
  • Discovery needs an interactive terminal: pass --include a,b --enable, or use --no-discover to save a disabled config.
  • OAuth server connects but calls fail: run anyy mcp login SERVER_ID and confirm a token was stored.
  • Changes did not apply: run anyy mcp reload SERVER_ID or restart the resident gateway.