[FEAT] MCP servers

[xsa-dev]

Is your feature request related to a problem? Please describe.
Integrating new tools and data sources into the assistant currently requires bespoke adapters per service. This leads to:
• High integration/maintenance cost and duplicated logic (auth, retries, schema validation, timeouts).
• Limited portability and vendor lock-in for tool integrations.
• Inconsistent UX for permissions/consent and low visibility into what a tool can do.
• No standardized discovery of capabilities (what resources, tools, or prompts are available) and no uniform way to stream progress/results.

Describe the solution you’d like
Add first-class support for MCP (Model Context Protocol) servers as a standard way to connect external tools and data into the assistant.

Scope (MVP):
• MCP client layer in the assistant runtime:
• Connect to one or more MCP servers.
• Support common transports (e.g., stdio for local processes and HTTP/SSE for remote).
• Negotiate capabilities and enumerate tools, resources, and prompts exposed by servers.
• Invoke tools with structured arguments and receive structured results + progress events.
• List/preview resources (and fetch content) with size/type checks and safe truncation.
• Configuration & discovery:
• Config-driven registration of servers (env vars and config file).
• Example: per-server transport, command/url, args, env, scopes, timeout, retries.
• Allow runtime enable/disable and per-request allowlisting.
• User consent & safety:
• Per-server permission prompts (first use), with readable summaries of capabilities.
• Scoped access for sensitive resources, rate limiting, and logging.
• Developer ergonomics:
• Typed request/response wrappers and error taxonomy (user, server, transport, timeout).
• Unified tracing/logging around MCP calls.
• Test harness + sample servers for local dev.

Describe alternatives you’ve considered
• Custom adapters per integration: flexible but expensive to build/maintain; no reuse of broader ecosystem; inconsistent UX.
• “Plugins” via ad-hoc HTTP or SDKs: faster to start, but every provider differs in auth, pagination, streaming, and error semantics.
• Direct provider-specific features (e.g., proprietary Actions): convenient but couples us to a single provider and reduces portability.
• Internal RPC/gRPC microservices: great for first-party systems, but still leaves us without an open, discoverable protocol for third-party tools.

Additional context
Why MCP now?
• Standardizes how the assistant discovers capabilities and calls tools/resources.
• Lets us reuse community servers (filesystems, Git/GitHub, DBs, issue trackers, cloud docs, etc.).
• De-risks future provider changes by decoupling tool integrations from the core assistant.

Proposed configuration (example)

config/mcp.yaml

servers:

• name: filesystem
  transport: stdio
  command: mcp-server-filesystem
  args: ["--root", "./workspace"]
  env:
  ALLOW_GLOBS: "**/*"
  scopes: ["read"]
  timeout_ms: 30000
  retries: 2

• name: github
  transport: sse
  url: https://mcp.example.com/github
  headers:
  Authorization: Bearer ${GITHUB_TOKEN}
  scopes: ["repo:read", "issues:write"]
  timeout_ms: 45000

Runtime behavior (high level)
1. On startup, load mcp.yaml and establish connections lazily (first use) or eagerly (config flag).
2. For a user request, the planner/agent selects candidate MCP tools/resources based on names, descriptions, and scopes.
3. Prompt the user for consent if a server or scope is first-time or elevated.
4. Execute tool calls with streaming progress; surface partials and final results; log trace IDs.
5. Cache capability discovery (TTL) and handle reconnection with backoff.

API surface (internal)
• McpClient.connect(cfg): McpSession
• McpSession.listTools()/listResources()/listPrompts()
• McpSession.callTool(name, args, {signal, onProgress}) → {result, usage, logs}
• McpSession.readResource(uri, {range?})
• Error classes: McpUserError, McpServerError, McpTransportError, McpTimeoutError.

Acceptance criteria
• Can register ≥2 servers (one stdio, one sse) via config and use them in a single conversation.
• Tools are discoverable and invokable; resources are listable and fetchable with safe limits.
• First-use consent prompt appears with clear, human-readable capability summary.
• Errors are surfaced with actionable messages; retries/backoff are observable in logs.
• Docs include “Quickstart” + sample configs and a minimal end-to-end demo.

Security & privacy
• Per-server allowlist + scopes; redaction of secrets in logs.
• Sandboxing for local stdio where possible; max execution time and output size limits.
• Opt-in telemetry with anonymized event fields.

Out of scope (for initial PR)
• GUI server manager or in-app marketplace.
• Advanced policy engine; we’ll start with allowlist + scopes.
• WebSocket transport and hot-reload of servers (can follow).