Visitar URL original
VTCode/docs/guides/mcp-integration.md at main · vinhnx/VTCode · GitHub
Skip to content

Latest commit

 

History

History
419 lines (333 loc) · 27.8 KB

mcp-integration.md

File metadata and controls

419 lines (333 loc) · 27.8 KB

MCP Integration Guide

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.

MCP Specification Map

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.

Tool result boundary

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.

Configuring MCP Providers

Core [mcp] table

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.

UI configuration

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.

Provider transports

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.

Local code discovery with Sem

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 web search without an API key

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 backend services without an account

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 static site publishing without an account

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 long-term memory over OAuth

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 memcode

The 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.

Security and validation

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 = 262144

The 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.

Allowlist Behaviour

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, or logging patterns, 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 (configuration maps) 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):

This behaviour avoids situations where a restrictive provider configuration is silently bypassed by broader default patterns.

Example

[mcp.allowlist]
enforce = true

[mcp.allowlist.default]
resources = ["docs/*"]

[mcp.allowlist.providers.context7]
resources = ["journals/*"]

In this configuration:

  • context7 can access only journals/* 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.

Inspecting resources and MCP Apps

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 pager

vtcode 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.

Testing the Integration

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 -- --nocapture

The 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 --nocapture

Expect the test to take a little longer on the first run while npx downloads the server bundle.

Troubleshooting

  • 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, and retry_attempts appear 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.