MCP Config Reference

This page is the compact reference for Anyy's MCP client and MCP server bridge configuration. For setup workflow and safety guidance, see MCP Integration. Use the anyy mcp commands instead of hand-editing YAML when possible.

MCP client support is disabled until you enable it and configure servers. A server's tools are only exposed to a model when the matching mcp-<server> toolset is selected.

Root Shape

mcp:
  client:
    enabled: false
    session_idle_ttl_ms: 300000
    servers:
      docs:
        enabled: true
        display_name: Docs
        transport: stdio
        command: npx
        args: ["-y", "@example/mcp-server"]
        env:
          EXAMPLE_TOKEN: secret:mcp/docs/token
        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
        sampling:
          enabled: false

  server:
    enabled: false
    transport: stdio

Unknown fields fail config validation.

CLI Commands

Use these commands for normal setup and inspection:

anyy mcp add SERVER_ID --command CMD --enable --include tool_a,tool_b
anyy mcp configure SERVER_ID --include tool_a,tool_b --enable
anyy mcp list
anyy mcp show SERVER_ID
anyy mcp probe SERVER_ID
anyy mcp test SERVER_ID
anyy mcp reload [SERVER_ID]
anyy mcp logs [SERVER_ID]

--activate-toolset adds the matching mcp-<server> toolset to toolsets.default, but Anyy rejects activation when the server is not enabled or has no include list.

Client Fields

Field	Type	Default	Meaning
mcp.client.enabled	bool	false	Enables MCP client runtime.
mcp.client.session_idle_ttl_ms	int	300000	Idle TTL before a client session can be closed.
mcp.client.servers	map	empty	Server definitions keyed by server id.

Server ids may contain letters, digits, _, -, and .. The id is normalized for visible tool names and toolset names.

Server Definition

Field	Type	Default	Meaning
enabled	bool	false	Disabled servers stay in config but are not connected or exposed.
display_name	string	server id	Friendly label for status surfaces.
transport	string	inferred	stdio or http.
auth	string	none	HTTP auth posture: none, header, or oauth.
command	string	none	Executable for stdio servers.
cwd	string	none	Working directory for stdio; must be absolute when set.
args	list	empty	Arguments for the stdio command.
env	map	empty	Environment values for stdio servers. Sensitive values must use refs.
url	string	none	URL for http servers.
headers	map	empty	HTTP headers. Sensitive values must use refs.
startup	string	lazy	lazy, gateway, or session.
connect_timeout_ms	int	5000	Initial connect timeout.
call_timeout_ms	int	30000	Tool call timeout.
tools	map	defaults below	Tool filtering and policy.
sampling	map	disabled	Server-initiated model request limits.

Transport inference is simple: a server with command becomes stdio; a server with url becomes http. Set transport explicitly when the inference is not what you want.

Transports

stdio servers launch a local process and use the official MCP stdio transport: one UTF-8 JSON-RPC message per line over stdin/stdout. They require command, may set args, cwd, and env, and must not set url. auth must be empty or none.

http servers use the official Streamable HTTP transport. Anyy advertises its latest supported MCP protocol version during initialization, stores the negotiated version, and sends it in MCP-Protocol-Version on HTTP requests.

http servers require a valid url, may set headers, and must not set command or args. Their auth value may be empty, none, header, or oauth.

cwd is validated as an absolute path when present. Timeouts must be zero or positive; zero means the default is applied.

Environment And Secrets

MCP env and headers values can use secret:, env:, or file: references. Do not use the older secret://, env://, or file:// forms.

literal: is rejected for MCP secret-bearing fields. Values whose names or contents look sensitive, such as Authorization, *_TOKEN, api_key, password, or Bearer ..., must use a secret reference.

Good:

headers:
  Authorization: secret:mcp/docs/auth_header
env:
  GITHUB_TOKEN: env:GITHUB_TOKEN

Rejected:

headers:
  Authorization: "Bearer raw-token"
env:
  API_KEY: literal:raw-token

Tools Policy

MCP servers are treated as untrusted by default. If tools.include is empty, remote server-native tools are not exposed. Utility tools for resources or prompts can still be exposed when explicitly enabled and advertised by the server.

Field	Default	Meaning
include	empty	Exact MCP tool names to allow. Config validation rejects *.
exclude	empty	Tool names to deny when they would otherwise be allowed.
resources	false	Expose list_resources and read_resource utility tools when the server supports resources.
prompts	false	Expose list_prompts and get_prompt utility tools when the server supports prompts.
default_risk	empty -> read	Risk assigned to exposed server tools. anyy mcp add writes runtime-high.
approval_policy	empty -> none	Approval policy assigned to exposed server tools.
execution_policy	empty -> direct	Execution policy assigned to exposed server tools. anyy mcp add writes confirm.
output_visible_chars	6000	Model-visible output budget.
output_stored_chars	30000	Stored output budget.

When a tool is allowed, its visible name is:

mcp_<server>_<tool>

Server ids and tool names are lowercased and sanitized. For example, GitHub.Prod plus issues.search becomes the toolset mcp-github_prod and tool mcp_github_prod_issues_search.

Use original MCP tool names in include and exclude, not the sanitized visible names.

Risk And Execution Values

default_risk accepts:

read, runtime-low, runtime-high, config-low, config-high, credential-high, dangerous, and force-required.

approval_policy accepts none, hook, and always.

execution_policy accepts direct, audit, confirm, change_plan, and force_change_plan.

These policies do not replace global tool governance. They set the descriptor for tools coming from this MCP server.

Sampling

Sampling is disabled unless sampling.enabled is true.

Field	Default when enabled	Meaning
model_allowlist	empty	Models the MCP server may request.
max_tokens_cap	4096	Maximum requested output tokens.
timeout_ms	30000	Sampling call timeout.
max_rpm	10	Per-server request-rate cap.
tool_loop_limit	1	Tool-loop cap for sampled calls.

When sampling is enabled, every numeric limit must be positive after defaults are applied.

Anyy As An MCP Server

The mcp.server block exposes Anyy itself through an MCP bridge. It is off by default.

Field	Default	Meaning
enabled	false	Enable the server bridge.
transport	stdio	Only stdio is currently supported.
scopes	empty	Optional scope allowlist.
expose_approvals	false	Expose approval-related bridge features.
expose_tools	false	Expose selected Anyy tools through the bridge.

Allowed scopes are conversations, messaging, approvals, tasks, reminders, memory, skills, and tools.

Operational Notes

Changing config.yaml does not automatically update already connected MCP sessions. Use anyy mcp reload [SERVER_ID] after edits, or restart the resident gateway.

Use anyy mcp probe SERVER_ID or anyy mcp test SERVER_ID to inspect server health and discovered tools. Use anyy mcp logs SERVER_ID when a server fails to start or connect.