MCP Servers

Ante can connect to Model Context Protocol servers to surface their tools to the agent. Servers can run as local subprocesses over stdio or connect over Streamable HTTP. Their tools become callable like any built-in tool.

Configuration

MCP servers are declared in ~/.ante/settings.json under the mcp_servers map. The key is the local server name; the value describes how to launch or connect to it.

{
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"]
    },
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": { "GITHUB_TOKEN": "ghp_..." }
    },
    "remote": {
      "url": "https://mcp.example.com/mcp"
    }
  }
}

Field	Required	Description
command	For stdio	Executable to spawn the server process; mutually exclusive with url
url	For Streamable HTTP	The server's Streamable HTTP endpoint; mutually exclusive with command
transport	No	stdio, streamable-http, or http (an alias for streamable-http). Inferred from command or url when omitted
args	No	Arguments passed to the command (stdio only)
env	No	Environment variables set on the server process (stdio only)
headers	No	HTTP headers sent with every request (Streamable HTTP only). Values take ${NAME}, ${NAME:-default}, and ${session_id}. See Authentication
enabled_tools	No	Allowlist of raw tool names to expose. When empty or absent, all tools from the server are exposed

For stdio, Ante spawns the command, speaks MCP over its stdin/stdout, and forwards stderr to the log.

For Streamable HTTP (Ante v0.2.12 or newer), Ante connects directly to url. Replace the example URL above with your server's Streamable HTTP endpoint. No bridge such as mcp-remote is needed, and a remote connection does not require Node.js. To migrate an existing bridge configuration, replace command and args with url and remove any env entries; keep enabled_tools if you use an allowlist.

Set exactly one of command or url. An explicit transport must match it. Legacy HTTP+SSE (transport: "sse") is unsupported. Conflicting settings, unsupported transports, or nonempty args or env on a URL server fail that server during warm-up with an explanatory message.

Use the endpoint URL directly: HTTP redirects are not followed.

Authentication

A remote server authenticates one of two ways.

OAuth sign-in. Most hosted servers (Linear, Notion, and others) offer OAuth. Configure only the url, then sign in once:

ante auth login linear

Ante discovers the server's sign-in, opens your browser, and stores the result under the server's name. It refreshes the sign-in on its own. Run ante auth logout linear to forget it. When nothing is stored, Ante connects without credentials, and a server that needs a sign-in reports it.

A token in headers. For a server that takes an API key or a personal access token, set an Authorization header. Ante sends it as written and skips the OAuth sign-in. Read the token from the environment so it stays out of the settings file:

{
  "mcp_servers": {
    "linear": { "url": "https://mcp.linear.app/mcp" },
    "github": {
      "url": "https://api.githubcopilot.com/mcp/",
      "headers": { "Authorization": "Bearer ${GITHUB_TOKEN}" }
    }
  }
}

Other headers are sent as well, and ${session_id} fills in the current session's ID. A ${NAME} with no value and no default fails that server at connect, naming the variable.

Tool naming

Each tool offered by a server is exposed to the agent as mcp__<server>__<tool>. Non-alphanumeric characters in either part are replaced with _, so a server keyed my-server with a tool named do.thing becomes mcp__my_server__do_thing.

MCP tools obey the same --tools / --include-tools / --exclude-tools filtering as built-in tools. A restrictive --tools base that doesn't name them will strip them. To shape what each server exposes regardless of the session filter, use enabled_tools:

{
  "mcp_servers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/tmp"],
      "enabled_tools": ["read_text_file", "write_file"]
    }
  }
}

Lifecycle

In the interactive TUI, MCP warm-up runs lazily in the background so the daemon stays responsive. When a session starts:

1. SessionStart and the initial ExtensionRefreshed fire immediately — the input is usable right away.
2. A background task connects to all configured servers in parallel. Each handshake attempt gets a 15-second deadline, followed by a separate 15-second deadline for listing all pages of tools.
3. Once discovery finishes across all servers, successfully discovered tools are registered together and become callable on the next turn (in-flight turns hold a frozen snapshot).
4. A second ExtensionRefreshed is emitted once warm-up finishes so the /mcp panel populates with each server's discovered tool list.

Progress is surfaced to the user via a grouped notification (an InfoBlockStart plus follow-up InfoBlockAppend events — see the protocol reference):

* Warming up 4 MCP servers — tools become available as servers connect.
  └ MCP ready: 4/4 servers connected, 60 tools registered.

Servers that fail to connect (or fail to list their tools) are logged, skipped, and reported as a child line under the warm-up block. Local server processes are kept alive for the duration of the session and terminated when the daemon exits.

Headless runs (ante -p) block before their first prompt until MCP warm-up finishes. A turn's tool schema is frozen when that turn starts, so this ensures configured MCP tools are present for a one-turn headless task. ante doctor skips MCP warm-up entirely.

Protocol compatibility

For both transports, Ante tries initialize first. If the server refuses with a JSON-RPC error, Ante opens a fresh connection (restarting the subprocess for stdio) and tries server/discover for revision 2026-07-28, with a fresh 15-second deadline. Timeouts, disconnects, and other handshake failures are reported without that fallback. For stdio servers, keep protocol messages on stdout and diagnostics on stderr.

Ante answers server pings but does not advertise sampling, elicitation, or roots capabilities. Sampling requests receive method-not-found, elicitation is declined, and roots are empty.

Tool-call timeout

Each MCP tool call has a 10-minute deadline so a hung server cannot pin a turn indefinitely. Set ANTE_MCP_TOOL_TIMEOUT to a positive number of whole seconds to change it for all MCP calls in the process:

ANTE_MCP_TOOL_TIMEOUT=120 ante

Zero, negative, or unparseable values keep the 600-second default. This setting covers tools/call; it does not change the initialization or tool-list deadlines above.

Timeouts and interrupted calls send a best-effort notifications/cancelled for that request while preserving the shared server connection. A cancellation notification does not guarantee that the server has stopped its work.

Tool results

Text-only results remain readable strings in ToolEnd.result_json. Rich results retain the full MCP result object, including content blocks, structuredContent, and error status. Ante also supplies supported text, images, and embedded PDFs to the model. Structured data is included without duplicating an equivalent JSON text block. Resource links are described, not fetched automatically; audio and unsupported binary content remain in the client result with a text notice to the model. Images are validated and resized before entering model history; invalid images produce an omission notice while their original data remains in the client result.

The /mcp command

In the TUI, run /mcp to inspect configured servers. The selector lists each server with its connection status, exposed tool count, and command or remote URL. Press Enter on a server to see per-tool details (description and parameters), or d to remove the server from settings.json.

Adding new servers is done by editing ~/.ante/settings.json directly; the selector does not currently include an in-TUI add flow.

Approval

MCP tools do not require approval by default. Use --exclude-tools or permission rules to gate specific tools if needed.