This guide outlines how VT Code connects to external MCP (Model Context Protocol) servers, how allowlists control tool
access, and how to troubleshoot common configuration issues. The configuration surface documented below maps directly to
the serde structures in crates/codegen/vtcode-config/src/mcp.rs, so the examples here stay aligned with the loader
that powers the CLI and the reusable vtcode-config crate. For the canonical protocol behaviour and the latest
server/client expectations, consult the upstream MCP reference index at https://modelcontextprotocol.io/llms.txt. That
index links to the full architecture, transport, authorisation, logging, and resource specification documents maintained
by the MCP community.
Developer Note: If you're implementing MCP module features or integrating with the core MCP APIs, see the MCP Integration Guide for API reference, code patterns, and implementation status.
Maintainer Note: If you maintain an external MCP server or client, see the MCP interop guide for what VT Code implements on each side of the protocol and how to test against it.
The llms.txt index enumerates every normative reference you may need while configuring VT Code. When you need deeper
protocol detail, jump straight from this guide to the most relevant specification chapter:
| Topic | Primary reference |
|---|---|
| Architecture, lifecycle, and key changes | Architecture overview, Lifecycle, Changelog |
| Transports and cancellation | Transports, Cancellation, Progress |
| Server-side concepts | Server overview, Tools, Resources, Prompts, Logging, Pagination |
| Client responsibilities | Client overview, Sampling, Elicitation |
| Security and governance | Security best practices, Authorization, Understanding authorization, Governance |
| Tooling and debugging | MCP Inspector, Example clients, Example servers |
Keep the specification open while editing vtcode.toml; VT Code intentionally mirrors the naming and behavioural
guarantees defined there.
VT Code returns successful MCP calls in an envelope containing provider and tool, plus content
when nonempty and structuredContent whenever supplied (including an empty object or explicit null).
Content order, public annotations, text, and media fields are retained. Structured application data is
preserved without schema enforcement, including application fields named _meta.
Protocol _meta is omitted at the result, content-block, and embedded-resource envelope levels; it is
never renamed to meta or exposed as a tool result. This follows the visibility boundary described in
OpenAI's MCP server guide.
An isError: true result remains an error with provider/tool context. Its message is the first nonempty
public text block, or Unknown MCP tool error when none exists. Hidden metadata never supplies error text.
Absent or false error flags remain successful results.
The generic terminal renderer gives displayable content precedence. When content produces no rows,
it formats all application fields in structuredContent using the existing JSON formatter, falling back
to a JSON literal if formatting produces no visible rows (including {} and empty or whitespace-only strings).
Embedded resources show their URI, optional media type, and public text body. Resource links show their URI
and name. Images and audio show a content marker and media type; binary image/audio/blob payloads are not printed.
These content rows take precedence over the structured fallback. Rendering never fetches resource URIs or plays audio.
Configured custom renderer profiles keep their existing behavior.
Open vtcode.toml and ensure the global MCP section is enabled. The top-level table mirrors the McpClientConfig
defaults, letting you tune concurrency, timeout, and transport behaviour in one place. All values fall back to the
defaults compiled into vtcode-config, summarised in the following table:
| Key | Default | Purpose |
|---|---|---|
enabled |
false |
Turns all MCP wiring on or off at once. |
max_concurrent_connections |
5 |
Global connection pool shared across providers. |
request_timeout_seconds |
30 |
Envelope timeout for lifecycle requests (mirrors MCP Lifecycle). |
retry_attempts |
3 |
Retry budget for transport failures before surfacing an error. |
startup_timeout_seconds |
null |
Optional provider start handshake timeout; inherits request_timeout_seconds when unset. |
tool_timeout_seconds |
null |
Optional per-tool guard for long-running operations. |
experimental_use_rmcp_client |
true |
Enables the Rust MCP client so HTTP/streamable transports are available. |
requirements |
enforce = false |
Optional transport-identity allowlist for admitting providers during initialization. |
ui |
mode = "compact", max_events = 50, show_provider_names = true |
Controls event rendering inside the TUI. |
Configure overrides as needed:
[mcp]
enabled = true
max_concurrent_connections = 3
request_timeout_seconds = 45
retry_attempts = 2
startup_timeout_seconds = 90 # optional: provider startup handshake window
tool_timeout_seconds = 45 # optional: per-tool execution deadline
experimental_use_rmcp_client = true
[mcp.requirements]
enforce = false
allowed_stdio_commands = ["uvx", "npx"]
allowed_http_endpoints = ["https://mcp.example.com/api"]startup_timeout_seconds defaults to None, which falls back to the global request_timeout_seconds value. Setting it
to 0 disables the startup timeout entirely—handy for first-run npm downloads. tool_timeout_seconds behaves the same
way for individual tool calls. When mcp.requirements.enforce = true, providers whose stdio command or HTTP
endpoint is not allowlisted are skipped during MCP initialization.
Configure the MCP UI panel if desired. Renderer profiles let you pick tailored output formats for specific providers or
tool prefixes. Renderer identifiers correspond to the enums defined in McpRendererProfile, so the strings in your TOML
match the canonical variants used in code:
[mcp.ui]
mode = "compact"
max_events = 25
show_provider_names = false
apps = "off"
[mcp.ui.renderers]
"context7" = "context7"
"sequential-thinker" = "sequential-thinking"apps selects the MCP Apps presentation tier: "off" (default) refuses app UI without fetching ui://
resources and emits an app.sandbox_denied event naming the refused URIs, "static" opts into disclosure rows plus
a sanitized structural preview on surfaces that support it, and "interactive" is reserved for a future sandboxed
webview host and is currently rejected at MCP startup. Only "interactive" advertises the
io.modelcontextprotocol/ui extension to servers, since a static preview cannot honor app round-trips. Neither the
disclosure nor the suppression marker ever enters model context. Explicit vtcode mcp resources / vtcode mcp app
reads stay available at every tier since they are direct user requests, not ambient enrichment.
At static and above, app results render in the terminal as a disclosure block rather than the app itself: an
[app: <name>] <uri> row, the served MIME type and byte count, the declared permissions and CSP domains when the
resource was fetched successfully, and a not rendered footer naming the clients that can run the app. Fetches are
best-effort and bounded (four URIs, five seconds total per tool result); when a fetch fails the linkage row stands
alone. At off, no app rows render; the refusal surfaces as an [APP DENIED] terminal line (or a desktop notice and
an ATIF step) instead. All server-originated strings in the block are control- and bidi-neutralized before display.
Define one or more providers. Stdio transports embed the command, arguments, and optional working directory directly in the provider table. VT Code forwards every value here into the MCP lifecycle as described in the stdio transport spec:
[[mcp.providers]]
name = "time"
enabled = true
command = "uvx"
args = ["mcp-server-time"]
working_directory = "./servers/time"
max_concurrent_requests = 2
startup_timeout_ms = 15_000
[mcp.providers.env]
PYTHONUNBUFFERED = "1"For HTTP transports, specify the endpoint and headers in place of the stdio fields. The configuration loader automatically deserializes either transport variant and populates provider metadata used by the MCP client registry:
[[mcp.providers]]
name = "figma"
enabled = true
max_concurrent_requests = 4
endpoint = "https://mcp.figma.com/mcp"
api_key_env = "FIGMA_MCP_TOKEN"
protocol_version = "2025-06-18"
headers = { "X-Client" = "vtcode", "X-MCP-App" = "vtcode" }Environment variables defined under [mcp.providers.env] are forwarded to stdio transports and composed with the
curated whitelist the loader already exposes. Use working_directory to stage local binaries, credentials, or fixtures
that the provider expects on disk. For HTTP transports, protocol_version determines which MCP schema the client
negotiates (the default is the current stable 2025-11-25; you can pin an older supported revision when providers
publish compatible endpoints). The handshake strategy selects the rmcp lifecycle: legacy (default) performs the
initialize handshake directly, while auto first probes server/discover and falls back to legacy. Prefer auto
only for modern servers — legacy-only servers would otherwise pay the discover-timeout penalty on every connect.
vtcode mcp get <name> reports the configured handshake, and the model-facing mcp list_servers action reports the
actually negotiated_protocol_version per connected server. Custom headers values help satisfy hosted provider
requirements for client identification—check the server's docs for required Authorization formats per the MCP
authorization guidance. The
max_concurrent_requests guard prevents a single provider from starving the global pool configured in [mcp]. Two
transport-level behaviors are fixed by policy rather than configuration: the HTTP client never follows redirects (custom
auth headers must not leak to cross-origin redirect targets), and the rmcp peer response cache is bounded (128 entries),
provider-partitioned, and never serves stale responses on transport errors — tool catalog staleness is owned by the
registry's list_changed refresh instead. Full tool definitions (get_tool_details) additionally expose the server's
outputSchema when advertised, so callers can type the result shape without an extra round trip.
Note: Streamable HTTP support is still evolving. The client negotiates the declared
protocol_version, but servers must expose Server-Sent Events per the transport spec. If an HTTP provider lacks streaming, fall back to a stdio wrapper until the server adopts the reference implementation.
Sem MCP provides optional local entity search, caller inspection, and structural diffs. The example configuration pins the server version and requires an explicit repository path. It preserves built-in file tools and existing approval controls; validation tools can execute repository commands.
Parallel Search MCP provides opt-in web search and page extraction over Streamable HTTP. Use the runnable TOML example to add the anonymous endpoint alongside your existing providers. It requires no Parallel API key or OAuth login; the free tier is rate limited.
Cohesivity MCP lets the agent provision Postgres, Redis, object storage, hosting, login and email for the app it is building, over Streamable HTTP. Use the runnable TOML example to add the anonymous endpoint alongside your existing providers. It requires no account or API key; new projects expire after 72 hours unless claimed.
deed.page MCP lets the agent publish the HTML pages, reports and small static sites it builds to a permanent public URL, then update, roll back or delete them, over Streamable HTTP. Use the runnable TOML example to add the anonymous endpoint alongside your existing providers. It requires no account or API key; free sites are public.
Memcode exposes an optional hosted Streamable HTTP server for persistent personal memory. VT Code
keeps its own ThreadEvent log as the authoritative session record; Memcode contributes separate MCP tools only when
you enable this provider.
VT Code currently expects a pre-registered OAuth client. Register its fixed loopback callback once and copy the returned
client_id:
curl --request POST https://memory.memcode.in/auth/mcp/oauth/register \
--header 'Content-Type: application/json' \
--data '{
"client_name": "VT Code",
"redirect_uris": ["http://localhost:8768/auth/callback"],
"token_endpoint_auth_method": "none",
"grant_types": ["authorization_code", "refresh_token"],
"response_types": ["code"],
"scope": "memory:connections:write memory:read memory:write",
"application_type": "native"
}'Then add the provider to vtcode.toml, replacing the placeholder with that public client ID:
[mcp]
enabled = true
experimental_use_rmcp_client = true
[[mcp.providers]]
name = "memcode"
enabled = true
endpoint = "https://mcp.memcode.in/i/vtcode/mcp"
protocol_version = "2025-11-25"
[mcp.providers.oauth]
authorization_url = "https://app.memcode.in/oauth/authorize"
token_url = "https://memory.memcode.in/auth/mcp/oauth/token"
client_id = "<client-id-from-registration>"
scopes = ["memory:connections:write", "memory:read", "memory:write"]
callback_port = 8768
extra_auth_params = { resource = "https://mcp.memcode.in/mcp" }
extra_token_params = { resource = "https://mcp.memcode.in/mcp" }Authorize it interactively before the first session:
vtcode mcp login memcodeThe browser flow uses PKCE and VT Code stores and refreshes the resulting token through its configured credential store.
Tokens are bound to the provider name, OAuth configuration, and MCP endpoint. Run vtcode mcp login <name> again
after changing those settings or upgrading from an unbound legacy token; legacy tokens are not automatically reused.
OAuth endpoints are validated before any network or browser activity: authorization_url, token_url, and the
protected resource must be http(s) URLs with a host, so dangerous schemes (javascript:, data:, file:) fail at
prepare time instead of reaching the browser opener or HTTP client.
Do not add an API key or static Authorization header. Apply the normal MCP allowlist and approval controls to the
memory tools, store only explicitly approved facts or verified outcomes, and treat retrieved memories as context rather
than instructions. Disabling the provider returns VT Code to its built-in session memory with no external dependency.
VT Code exposes additional security gates through the [mcp.security] table. Enable authentication and tighten rate
limits or validation rules when running sensitive providers. These settings mirror the guidance in the MCP
security best practices
chapter:
[mcp.security]
auth_enabled = true
api_key_env = "VT_MCP_API_KEY"
[mcp.security.rate_limit]
requests_per_minute = 120
concurrent_requests = 6
[mcp.security.validation]
schema_validation_enabled = true
path_traversal_protection = true
max_argument_size = 262144The same structure powers the optional embedded MCP server (vtcode as a provider). Combine the security block with the
[mcp.server] table to expose curated tools over SSE or HTTP. Ensure your tool list lines up with the
server tools contract:
[mcp.server]
enabled = true
bind_address = "127.0.0.1"
port = 3030
transport = "sse"
exposed_tools = ["read_file"]vtcode-config re-exports serde schemas for these tables, making it straightforward to validate configuration files in
automation or IDE tooling.
MCP access is gated by pattern-based allowlists. The defaults apply to every provider unless the provider supplies its own patterns. Provider-specific rules now fully override the defaults:
- When a provider defines
tools,resources,prompts, orloggingpatterns, only matches in that provider block are accepted. Default rules are ignored for that provider. - If a provider omits a rule set, VT Code falls back to the default patterns.
- Configuration permissions (
configurationmaps) continue to support provider overrides via an explicit match or by delegating to the default rules.
Each allowlist key maps directly to the Model Context Protocol concepts described in the official specification (all
cited in llms.txt):
toolscorrespond to tool definitions, letting you scope remote execution entry points.resourcesalign with resource handles exposed by a server.promptsconstrain server-authored prompt templates.loggingmirrors logging channels surfaced by compliant servers.
This behaviour avoids situations where a restrictive provider configuration is silently bypassed by broader default patterns.
[mcp.allowlist]
enforce = true
[mcp.allowlist.default]
resources = ["docs/*"]
[mcp.allowlist.providers.context7]
resources = ["journals/*"]In this configuration:
context7can access onlyjournals/*resources.- Other providers continue to match
docs/*through the default rule.
Enable enforce = true when you want the rules to be mandatory; leaving it unset keeps legacy behaviour where allowlist
checks are advisory only.
Two read-only commands orient you on a live server without starting a session. Both load the workspace-layered configuration, so they observe the same providers, allowlists, and timeouts as the agent runtime:
vtcode mcp resources # table of every exposed resource (URI, provider, type, size)
vtcode mcp resources --provider docs # restrict to one provider
vtcode mcp app 'ui://docs/app.html' # inspect one resource: MIME, byte count, declared UI posture
vtcode mcp app 'ui://docs/app.html' --html # print the raw body (e.g. HTML source) to the pagervtcode mcp app never executes the resource. For ui:// app resources it additionally reports the declared
permissions and CSP domains from the resource's _meta.ui, and warns when the served MIME type is not
text/html;profile=mcp-app. Both commands accept --json for scripting (--html and --json conflict).
Tools a server marks _meta.ui.visibility: ["app"] stay hidden from the agent: they never appear in tool
listings or the synced .vtcode/mcp/tools/ discovery files, and a direct model-originated call is rejected
with an app-only error. Omitted visibility means visible to both model and app; a malformed value hides the
tool from the model. Enforcement for app-originated calls awaits an interactive app engine.
Run the MCP-focused test suite to verify configuration parsing, allowlist enforcement, and registry wiring. These tests exercise the serde types documented above and confirm compatibility with the schema reference:
cargo test -p vtcode-core mcp -- --nocaptureThe suite includes mocked clients and parsing tests so it does not require live MCP servers. For an end-to-end check
against the Context7 MCP server, invoke the ignored smoke test which spawns the official @upstash/context7-mcp package
on demand. This mirrors the example servers highlighted in the MCP
documentation:
cargo test -p vtcode-core --test mcp_context7_manual context7_list_tools_smoke -- --ignored --nocaptureExpect the test to take a little longer on the first run while npx downloads the server bundle.
- Unexpected tool execution permissions – confirm whether the provider defines its own allowlist. Provider rules now override defaults, so missing patterns may block tools that defaults would otherwise allow.
- Provider handshake visibility – VT Code now sends explicit MCP client metadata and normalizes structured tool responses. Context7 results surface as plain JSON objects in the tool panel so downstream renderers can display status, metadata, and message lists without additional post-processing.
- Stale configuration values – ensure
max_concurrent_connections,request_timeout_seconds, andretry_attemptsappear under the[mcp]table after any nested[mcp.ui]section. TOML resets the table context when a new header appears. - HTTP transport issues – VT Code currently performs capability probing for HTTP MCP servers but requires a streaming implementation to be fully functional. Use stdio transports when possible.
With these settings and checks in place, MCP providers and allowlists should behave predictably, unlocking additional context-aware tooling in VT Code.