Use MCP Servers

Use this guide when an external MCP server already provides the tool surface you need and you want Anyy to expose only a small, reviewable subset of it.

For the complete config model, see MCP Integration. For the compact field table, see MCP Config Reference.

When To Use MCP

Use MCP when:

a useful external tool already exists as an MCP server,
you want a clean RPC boundary to a local or hosted system,
you need per-server tool filtering, or
you want to connect one internal system without adding an Anyy native tool.

Do not use MCP when a built-in Anyy tool already solves the job, or when the server exposes a broad destructive surface that you are not ready to filter.

Mental Model

MCP is an adapter layer:

Anyy remains the assistant and resident runtime.
MCP servers contribute external tools.
Anyy filters those tools before the model can use them.
Each server maps to a mcp-<server> toolset.

Good MCP setup is not "connect everything." It is "connect the smallest useful tool surface."

Add One Server First

Start with one low-risk server and an include list:

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

Check what was saved:

anyy mcp list
anyy mcp show project_fs

--activate-toolset adds mcp-project_fs to toolsets.default for new sessions. Anyy rejects activation unless the server is enabled and has a non-empty include list.

Verify Runtime Visibility

With the gateway running:

anyy mcp probe project_fs
anyy mcp test project_fs
anyy mcp status

After changing config, reload the server or restart the gateway:

anyy mcp reload project_fs

Then ask in a fresh or reloaded session:

Which MCP-backed tools are available right now?

If the tools still do not appear, check all visibility gates:

Gate	Check
Client enabled	`mcp.client.enabled: true`
Server enabled	`mcp.client.servers.<id>.enabled: true`
Tools allowed	`tools.include` contains server-native tool names
Toolset active	`mcp-<server>` is selected for the session or in `toolsets.default`

Filter Immediately

Prefer allowlists:

anyy mcp configure github \
  --include list_issues,create_issue \
  --enable \
  --activate-toolset

In YAML, use original MCP tool names in include and exclude:

mcp:
  client:
    enabled: true
    servers:
      github:
        enabled: true
        tools:
          include: [list_issues, create_issue]
          resources: false
          prompts: false

Sanitized Anyy tool names look like mcp_github_list_issues, but the filter list uses server-native names.

Use Hosted MCP Servers

HTTP servers use URLs:

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

Store a complete sensitive header value in the secret when the remote server expects a value such as Bearer .... Sensitive env and headers values must use secret:, env:, or file: references; literal: is rejected for secret-bearing MCP fields.

For OAuth servers:

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

anyy mcp login linear

Plain HTTP URLs are allowed only for local endpoints. Use HTTPS for remote servers.

Run Anyy As An MCP Server

When another MCP client should talk to Anyy, run:

anyy mcp serve

The Anyy MCP server bridge currently uses stdio transport. Enable only the scopes the client needs under mcp.server.

Common First Patterns

Pattern	Start with
Local project assistant	Filesystem server rooted to one project directory.
Issue triage	GitHub server with read/list/create issue tools only.
Internal API assistant	Hosted MCP server with read-heavy include list.
Documentation server	Enable resource/prompt utilities only when the server supports them and you need them.

Expand the include list only after you have a concrete prompt that needs another tool.

Troubleshooting

Symptom	Check
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 calls fail	Run `anyy mcp login SERVER_ID`.
Runtime did not update	Run `anyy mcp reload SERVER_ID` or restart the resident gateway.
Too many tools appear	Narrow `tools.include` and disable `resources`/`prompts` unless needed.
Remote HTTP URL is rejected	Use HTTPS, or keep plain HTTP to local endpoints only.

When To Use MCP​

Mental Model​

Add One Server First​

Verify Runtime Visibility​

Filter Immediately​

Use Hosted MCP Servers​

Run Anyy As An MCP Server​

Common First Patterns​

Troubleshooting​