# MCPProxy Documentation

> Smart MCP Proxy for AI Agents

This file contains links to documentation sections following the llmstxt.org standard.

## Table of Contents

- [Introduction](https://docs.mcpproxy.app/): MCPProxy - Smart MCP Proxy for AI Agents with intelligent tool discovery, security quarantine, and Docker isolation
- [Installation](https://docs.mcpproxy.app/getting-started/installation): Install MCPProxy on macOS, Windows, or Linux
- [Quick Start](https://docs.mcpproxy.app/getting-started/quick-start): Get MCPProxy running in 5 minutes
- [Find out why an agent cannot use a tool](https://docs.mcpproxy.app/guides/diagnose-unavailable-tool): Trace a missing or failing MCP tool through client connection, server state, review, access policy, discovery and Activity, then verify the fix.
- [Keep a growing tool catalog out of initial context](https://docs.mcpproxy.app/guides/discover-tools-on-demand): Compare direct and on-demand MCP tool exposure, then prove the agent still completes a real task.
- [Guides](https://docs.mcpproxy.app/guides): Complete MCPProxy tasks: share one setup across clients, diagnose unavailable tools, discover tools on demand, and review tool definitions before use.
- [Review a tool before exposing it to your agent](https://docs.mcpproxy.app/guides/review-tool-before-use): Inspect and approve a first server deliberately, then handle a changed tool definition without bypassing the review hold.
- [Reuse one MCP setup in two AI clients](https://docs.mcpproxy.app/guides/two-clients-one-setup): Connect Claude Code and Codex to one local MCPProxy instance, review a documentation upstream once, and verify a real tool call from each client.
- [Configuration File](https://docs.mcpproxy.app/configuration/config-file): Complete reference for mcp_config.json
- [Environment Variables](https://docs.mcpproxy.app/configuration/environment-variables): Configure MCPProxy using environment variables
- [Sensitive Data Detection](https://docs.mcpproxy.app/configuration/sensitive-data-detection): Configure sensitive data detection for MCP tool calls
- [Upstream Servers](https://docs.mcpproxy.app/configuration/upstream-servers): Configure MCP servers to connect through MCPProxy
- [Activity Commands](https://docs.mcpproxy.app/cli/activity-commands): CLI commands for querying and monitoring activity logs
- [Attention Command](https://docs.mcpproxy.app/cli/attention-command): mcpproxy attention prints the one needs-attention list every MCPProxy surface shares, and the same count leads mcpproxy status and mcpproxy doctor
- [Catalog Commands](https://docs.mcpproxy.app/cli/catalog-commands): mcpproxy catalog search, show and add: find a server across every catalog source, ranked the same way as the Web UI and macOS Add Server, and add i...
- [Command Reference](https://docs.mcpproxy.app/cli/command-reference): Complete CLI command reference for MCPProxy
- [Credential Commands](https://docs.mcpproxy.app/cli/credential-commands): Server edition: manage per-user stored credentials for shared upstream servers — stored, not injected.
- [Database Commands](https://docs.mcpproxy.app/cli/db-commands): Offline maintenance commands for the MCPProxy BBolt database - compaction and size statistics
- [Management Commands](https://docs.mcpproxy.app/cli/management-commands): CLI commands for managing upstream servers and monitoring health
- [Profile and Client Commands](https://docs.mcpproxy.app/cli/profile-commands): CLI commands to define profiles, bind clients and tokens to them, and explain why a tool is or is not available
- [Review Commands](https://docs.mcpproxy.app/cli/review-commands): CLI commands for reviewing quarantined servers and new or changed tools: list, show, approve and reject through the scan gate
- [Security Scanner Commands](https://docs.mcpproxy.app/cli/security-commands): CLI commands for managing security scanners, scanning upstream MCP servers, and reviewing findings
- [CLI Sensitive Data Commands](https://docs.mcpproxy.app/cli/sensitive-data-commands): CLI commands for querying activity logs with sensitive data detection
- [Status Command](https://docs.mcpproxy.app/cli/status-command): CLI command for viewing MCPProxy status, API key, and Web UI URL
- [MCP Protocol](https://docs.mcpproxy.app/api/mcp-protocol): MCPProxy's MCP protocol implementation and built-in tools
- [REST API](https://docs.mcpproxy.app/api/rest-api): MCPProxy REST API reference
- [Activity Log Page](https://docs.mcpproxy.app/web-ui/activity-log): Real-time monitoring and analysis of MCP server activity in the Web UI.
- [Home and Navigation](https://docs.mcpproxy.app/web-ui/dashboard): The MCPProxy web interface - Home and its needs-attention list, the grouped sidebar, the header, the command palette and the Add menu
- [Server Detail Page](https://docs.mcpproxy.app/web-ui/server-detail): Edit headers, env vars, and per-server config from the Web UI
- [Activity Log](https://docs.mcpproxy.app/features/activity-log): Track and audit AI agent tool calls with the Activity Log
- [Agent Instructions (CLAUDE.md / AGENTS.md)](https://docs.mcpproxy.app/features/agent-instructions): Help Claude Code, Codex and other agents find the tools behind mcpproxy instead of falling back to shell CLIs — what the proxy tells each client au...
- [Agent Tokens](https://docs.mcpproxy.app/features/agent-tokens): Scoped API credentials for AI agents with server and permission restrictions
- [Audit Log](https://docs.mcpproxy.app/features/audit-log): Attributable, redacted JSONL audit lines for every tool-call authorization decision, tool call and login attempt.
- [Per-User Auth Broker](https://docs.mcpproxy.app/features/auth-broker): Server-edition per-user OAuth connect flow — credentials are stored encrypted per user for a future broker and are not injected into upstream calls
- [Auto-Update](https://docs.mcpproxy.app/features/auto-update): One-click updates in the macOS tray, the channel-aware mcpproxy update CLI, and every switch that turns them off
- [Catalog popularity](https://docs.mcpproxy.app/features/catalog-popularity): How MCPProxy ranks catalog results using GitHub stars and Docker Hub pull counts.
- [Code Execution](https://docs.mcpproxy.app/features/code-execution): Execute JavaScript or TypeScript to orchestrate multiple MCP tools
- [Configuration Import](https://docs.mcpproxy.app/features/config-import): Import MCP server configurations from Claude Desktop, Claude Code, Cursor IDE, Codex CLI, and Gemini CLI
- [Connect Clients](https://docs.mcpproxy.app/features/connect-clients): Preview-before-write connect flow that registers mcpproxy in an MCP client's config file, with a sanitized disclosure of what is replaced and a pre...
- [Security Isolation (Docker · Sandbox · None)](https://docs.mcpproxy.app/features/docker-isolation): Confine MCP servers with Docker containers, native Landlock sandboxing, or no isolation
- [IdP Subject Token Storage (removed)](https://docs.mcpproxy.app/features/idp-token-storage): Server edition: the store_idp_tokens feature was removed; the key is accepted and ignored.
- [Intent Declaration](https://docs.mcpproxy.app/features/intent-declaration): Fine-grained permission control for AI tool calls with intent-based tool splitting
- [Keyring Integration](https://docs.mcpproxy.app/features/keyring-integration): Securely store and manage secrets using your operating system's native keyring
- [Linux Package Repositories](https://docs.mcpproxy.app/features/linux-package-repos): How the apt.mcpproxy.app and rpm.mcpproxy.app repositories work — retention, pinning, mirroring, troubleshooting.
- [Credential lifecycle over MCP](https://docs.mcpproxy.app/features/mcp-credential-lifecycle): Issue, inspect and revoke worker credentials (locked client credentials and profile-pinned agent tokens) from an administrator agent over MCP with ...
- [Needs Attention](https://docs.mcpproxy.app/features/needs-attention): The one needs-attention list every MCPProxy surface reads from — sign-in prompts, reviews, errors, missing secrets, configuration problems, unseen ...
- [OAuth Authentication](https://docs.mcpproxy.app/features/oauth-authentication): Configure OAuth 2.1 authentication for MCP servers
- [Observability](https://docs.mcpproxy.app/features/observability): Export Prometheus metrics and OpenTelemetry traces from MCPProxy to your own monitoring stack.
- [Output Sanitisation](https://docs.mcpproxy.app/features/output-sanitisation): Spotlight untrusted tool output, redact detected secrets, and strip control sequences at the response chokepoint.
- [Output-Schema Validation](https://docs.mcpproxy.app/features/output-schema-validation): Verify that a tool's structured response conforms to its declared outputSchema before it reaches the agent.
- [Profiles](https://docs.mcpproxy.app/features/profiles): Named views over your upstream servers with a tool policy: tier caps, rules, client and token bindings, anonymous confinement and an access explainer.
- [Quarantine State Machine Testing](https://docs.mcpproxy.app/features/quarantine-testing): Runtime invariants, multi-pass scenario tests, and property-based testing for the quarantine state machine
- [Adding Servers from Registries](https://docs.mcpproxy.app/features/registry-add): Add an upstream server by registry and server id; the daemon derives the runnable config and quarantines it for review.
- [Routing Modes](https://docs.mcpproxy.app/features/routing-modes): Configure how MCPProxy exposes upstream tools to AI agents
- [Native Sandbox Isolation](https://docs.mcpproxy.app/features/sandbox-isolation): Isolate stdio MCP servers on Linux without Docker using the Landlock LSM plus resource limits.
- [Security Scanner Images](https://docs.mcpproxy.app/features/scanner-images): Where the Docker images behind the security scanners come from and how they are published.
- [Schema-Deferred Direct Mode](https://docs.mcpproxy.app/features/schema-deferred-direct-mode): Enumerate every upstream tool on the direct surface without shipping its inputSchema — compact signatures now, full schemas on demand
- [Tool Search & Discovery](https://docs.mcpproxy.app/features/search-discovery): Intelligent tool discovery using BM25 search across all MCP servers
- [Security Quarantine](https://docs.mcpproxy.app/features/security-quarantine): Protect against Tool Poisoning Attacks with automatic server quarantine
- [Security Scanner Plugin System](https://docs.mcpproxy.app/features/security-scanner-plugins): Docker-based scanner plugins for detecting tool poisoning, prompt injection, CVEs, and supply-chain risks in upstream MCP servers
- [Sensitive Data Detection](https://docs.mcpproxy.app/features/sensitive-data-detection): Detect and flag sensitive data in AI agent tool call arguments and responses in the activity log
- [Settings Page](https://docs.mcpproxy.app/features/settings-page): The Web UI Configuration page: prioritized form sections over mcpproxy's config, with a raw JSON escape hatch.
- [Anonymous Telemetry](https://docs.mcpproxy.app/features/telemetry): What the anonymous daily heartbeat contains, what it never contains, and how to disable it.
- [Tool-Level Quarantine](https://docs.mcpproxy.app/features/tool-quarantine): SHA256 hash-based tool approval system to detect and block tool description changes
- [Deterministic Tool Scanner (Spec 076)](https://docs.mcpproxy.app/features/tool-scanner): The offline, deterministic in-process detection engine that scans MCP tool definitions for hidden-Unicode smuggling, cross-server shadowing, decode...
- [Required-Tools Preflight](https://docs.mcpproxy.app/features/tools-preflight): Deterministic, side-effect-free availability check for required tools before an automation spends model tokens
- [TOON Output](https://docs.mcpproxy.app/features/toon-output): Adaptive TOON encoding of tool-call results — token savings on tabular payloads, byte-identical passthrough everywhere else
- [Signed TPA Bundles (Spec 101)](https://docs.mcpproxy.app/features/tpa-bundle-signing): Sign, drop, verify, roll back and monitor an offline TPA signature corpus, with downgrade protection that works without a network, a daily refresh,...
- [Version Updates](https://docs.mcpproxy.app/features/version-updates): How MCPProxy checks for and displays version updates
- [Code Execution API Reference](https://docs.mcpproxy.app/code_execution/api-reference): Complete reference for the objects, functions, and limits available inside the code execution sandbox.
- [Code Execution Cookbook](https://docs.mcpproxy.app/code_execution/cookbook): Task-oriented recipes for common code execution patterns.
- [Code Execution Examples](https://docs.mcpproxy.app/code_execution/examples): Worked end-to-end examples of orchestrating upstream tools with code execution.
- [Code Execution Overview](https://docs.mcpproxy.app/code_execution/overview): How the sandboxed JavaScript/TypeScript runtime orchestrates multiple upstream MCP tools in one request.
- [Code Execution Troubleshooting](https://docs.mcpproxy.app/code_execution/troubleshooting): Diagnose sandbox errors, timeouts, and unexpected results in code execution.
- [Deploying for a Team (Kubernetes + Keycloak)](https://docs.mcpproxy.app/operations/deploying-for-a-team): Run the server edition (mcpproxy-server) on Kubernetes behind an ingress with Keycloak SSO: single-replica Deployment, group-based access, audit-to...
- [Linux Package Repositories — Operations](https://docs.mcpproxy.app/operations/linux-package-repos-infrastructure): Maintainer runbook for apt.mcpproxy.app / rpm.mcpproxy.app — infra layout, key rotation, manual republish, bad-version purge.
- [Reverse Proxy Deployment](https://docs.mcpproxy.app/operations/reverse-proxy): Run MCPProxy behind nginx or Caddy — fix "403 Forbidden: invalid Host header" with trusted_hosts, honour X-Forwarded-* only from trusted_proxies, a...
- [Shutdown Behavior](https://docs.mcpproxy.app/operations/shutdown-behavior): How MCPProxy handles graceful shutdown of upstream servers and subprocesses
- [MCPX_CONFIG_DEPRECATED_FIELD](https://docs.mcpproxy.app/errors/MCPX_CONFIG_DEPRECATED_FIELD): Your mcpproxy config uses a deprecated field that will be removed in a future release.
- [MCPX_CONFIG_INVALID_COMMAND](https://docs.mcpproxy.app/errors/MCPX_CONFIG_INVALID_COMMAND): A stdio server's command and args cannot spawn anything — typically a package runner with no package to run.
- [MCPX_CONFIG_MISSING_SECRET](https://docs.mcpproxy.app/errors/MCPX_CONFIG_MISSING_SECRET): An upstream config refers to a secret that does not exist in the secret store.
- [MCPX_CONFIG_PARSE_ERROR](https://docs.mcpproxy.app/errors/MCPX_CONFIG_PARSE_ERROR): mcpproxy could not parse the configuration file as JSON.
- [MCPX_DOCKER_DAEMON_DOWN](https://docs.mcpproxy.app/errors/MCPX_DOCKER_DAEMON_DOWN): The Docker daemon is not reachable; isolated upstream servers cannot run.
- [MCPX_DOCKER_EXEC_NOT_FOUND](https://docs.mcpproxy.app/errors/MCPX_DOCKER_EXEC_NOT_FOUND): The Docker isolation image is missing the interpreter the server needs (e.g. no uvx/node).
- [MCPX_DOCKER_IMAGE_PULL_FAILED](https://docs.mcpproxy.app/errors/MCPX_DOCKER_IMAGE_PULL_FAILED): Docker failed to pull the isolation image used by an upstream server.
- [MCPX_DOCKER_MISSING_TOOLCHAIN](https://docs.mcpproxy.app/errors/MCPX_DOCKER_MISSING_TOOLCHAIN): The Docker isolation image is missing a tool the server shells out to at runtime (most often git).
- [MCPX_DOCKER_NO_PERMISSION](https://docs.mcpproxy.app/errors/MCPX_DOCKER_NO_PERMISSION): The current user can't talk to the Docker socket.
- [MCPX_DOCKER_SNAP_APPARMOR](https://docs.mcpproxy.app/errors/MCPX_DOCKER_SNAP_APPARMOR): Snap-installed Docker on Ubuntu blocks mcpproxy's security scanner via AppArmor.
- [MCPX_HTTP_401](https://docs.mcpproxy.app/errors/MCPX_HTTP_401): The MCP server responded 401 Unauthorized.
- [MCPX_HTTP_403](https://docs.mcpproxy.app/errors/MCPX_HTTP_403): The MCP server responded 403 Forbidden — credentials valid but lack permission.
- [MCPX_HTTP_404](https://docs.mcpproxy.app/errors/MCPX_HTTP_404): The configured MCP endpoint URL returned 404 Not Found.
- [MCPX_HTTP_4XX](https://docs.mcpproxy.app/errors/MCPX_HTTP_4XX): The MCP server rejected the request with a 4xx status that has no more specific code.
- [MCPX_HTTP_5XX](https://docs.mcpproxy.app/errors/MCPX_HTTP_5XX): The MCP server responded with an HTTP 5xx status — upstream-side failure.
- [MCPX_HTTP_CANCELED](https://docs.mcpproxy.app/errors/MCPX_HTTP_CANCELED): The connection attempt was canceled by mcpproxy itself — shutdown, config reload, or a manual disconnect.
- [MCPX_HTTP_CONN_REFUSED](https://docs.mcpproxy.app/errors/MCPX_HTTP_CONN_REFUSED): TCP connection to the MCP server was refused.
- [MCPX_HTTP_CONN_RESET](https://docs.mcpproxy.app/errors/MCPX_HTTP_CONN_RESET): The TCP connection to the MCP server was reset by the peer before a reply arrived.
- [MCPX_HTTP_DNS_FAILED](https://docs.mcpproxy.app/errors/MCPX_HTTP_DNS_FAILED): DNS lookup for the configured MCP server hostname failed.
- [MCPX_HTTP_LEGACY_SSE](https://docs.mcpproxy.app/errors/MCPX_HTTP_LEGACY_SSE): The endpoint rejected the streamable-HTTP initialize POST with a 4xx — the signature of a server that only speaks the older SSE transport.
- [MCPX_HTTP_RATE_LIMITED](https://docs.mcpproxy.app/errors/MCPX_HTTP_RATE_LIMITED): The MCP server returned 429 Too Many Requests — mcpproxy is being rate-limited.
- [MCPX_HTTP_TLS_FAILED](https://docs.mcpproxy.app/errors/MCPX_HTTP_TLS_FAILED): TLS verification of the upstream server failed.
- [MCPX_NETWORK_OFFLINE](https://docs.mcpproxy.app/errors/MCPX_NETWORK_OFFLINE): The host appears to have no network connectivity.
- [MCPX_NETWORK_PROXY_MISCONFIG](https://docs.mcpproxy.app/errors/MCPX_NETWORK_PROXY_MISCONFIG): The system HTTP_PROXY / HTTPS_PROXY variables look misconfigured.
- [MCPX_OAUTH_CALLBACK_MISMATCH](https://docs.mcpproxy.app/errors/MCPX_OAUTH_CALLBACK_MISMATCH): The OAuth redirect URI used in the callback didn't match the one mcpproxy registered.
- [MCPX_OAUTH_CALLBACK_TIMEOUT](https://docs.mcpproxy.app/errors/MCPX_OAUTH_CALLBACK_TIMEOUT): The OAuth browser callback did not arrive in time.
- [MCPX_OAUTH_DISCOVERY_FAILED](https://docs.mcpproxy.app/errors/MCPX_OAUTH_DISCOVERY_FAILED): mcpproxy could not fetch the OAuth metadata document from the upstream server.
- [MCPX_OAUTH_LOGIN_REQUIRED](https://docs.mcpproxy.app/errors/MCPX_OAUTH_LOGIN_REQUIRED): The server requires an OAuth sign-in before it can connect (first-time login).
- [MCPX_OAUTH_REAUTH_REQUIRED](https://docs.mcpproxy.app/errors/MCPX_OAUTH_REAUTH_REQUIRED): A previously working OAuth token is no longer valid; sign in again.
- [MCPX_OAUTH_REFRESH_403](https://docs.mcpproxy.app/errors/MCPX_OAUTH_REFRESH_403): The OAuth provider rejected the refresh token with HTTP 403.
- [MCPX_OAUTH_REFRESH_EXPIRED](https://docs.mcpproxy.app/errors/MCPX_OAUTH_REFRESH_EXPIRED): The stored OAuth refresh token has expired and cannot be silently renewed.
- [MCPX_QUARANTINE_PENDING_APPROVAL](https://docs.mcpproxy.app/errors/MCPX_QUARANTINE_PENDING_APPROVAL): This server has tools awaiting security approval; they will not run until approved.
- [MCPX_QUARANTINE_TOOL_CHANGED](https://docs.mcpproxy.app/errors/MCPX_QUARANTINE_TOOL_CHANGED): A previously approved tool changed its description or schema; re-approval is required.
- [MCPX_STDIO_EXIT_BEFORE_INITIALIZE](https://docs.mcpproxy.app/errors/MCPX_STDIO_EXIT_BEFORE_INITIALIZE): The stdio MCP server process exited before completing the MCP initialize handshake.
- [MCPX_STDIO_EXIT_NONZERO](https://docs.mcpproxy.app/errors/MCPX_STDIO_EXIT_NONZERO): The stdio MCP server process exited with a non-zero status before completing the handshake.
- [MCPX_STDIO_HANDSHAKE_INVALID](https://docs.mcpproxy.app/errors/MCPX_STDIO_HANDSHAKE_INVALID): The stdio server replied, but the MCP handshake frame was malformed.
- [MCPX_STDIO_HANDSHAKE_TIMEOUT](https://docs.mcpproxy.app/errors/MCPX_STDIO_HANDSHAKE_TIMEOUT): The stdio server did not reply to the MCP initialize request in time.
- [MCPX_STDIO_SPAWN_EACCES](https://docs.mcpproxy.app/errors/MCPX_STDIO_SPAWN_EACCES): The OS denied permission to execute the stdio MCP server command.
- [MCPX_STDIO_SPAWN_ENOENT](https://docs.mcpproxy.app/errors/MCPX_STDIO_SPAWN_ENOENT): The configured command for a stdio MCP server was not found on PATH.
- [MCPX_UNKNOWN_UNCLASSIFIED](https://docs.mcpproxy.app/errors/MCPX_UNKNOWN_UNCLASSIFIED): mcpproxy could not classify this failure into a specific error code.
- [Error Code Catalog](https://docs.mcpproxy.app/errors/): Stable error codes emitted by mcpproxy with cause, symptoms, and remediation steps.
- [Architecture](https://docs.mcpproxy.app/development/architecture): MCPProxy internal architecture and component overview
- [Building](https://docs.mcpproxy.app/development/building): How to build MCPProxy from source
- [macOS Tray Development](https://docs.mcpproxy.app/development/macos-tray): Build, replace, and verify the Swift macOS tray app in native/macos/.
- [Quarantine/approval testing pilot](https://docs.mcpproxy.app/development/quarantine-approval-pilot): The pilot checks MCPProxy's quarantine and approval behaviour against an **independent reference model**, reports which selected requirements and s...
- [Release Qualification Gate](https://docs.mcpproxy.app/development/release-gate): Tag-blocking QA harness that produces one machine-readable pass/fail verdict before artifacts are published.
- [Server Multi-User Authentication](https://docs.mcpproxy.app/development/server-edition-multiuser-auth): SSO multi-user authentication for the server edition: generic OIDC (Keycloak, Okta, Auth0, Authentik, Entra) with JWKS-verified ID tokens, plus the...
- [Testing Guide](https://docs.mcpproxy.app/development/testing): How to run tests for MCPProxy
- [Verifying Web UI Changes](https://docs.mcpproxy.app/development/web-ui-verification): Playwright sweep and HTML report workflow for verifying changes to the Vue Web UI.
- [Contributing](https://docs.mcpproxy.app/contributing): How to contribute to MCPProxy documentation
- [CLI Client Mode](https://docs.mcpproxy.app/cli-client-mode): Use the mcpproxy CLI as an MCP client to call tools against a running proxy.
- [CLI Output Formatting](https://docs.mcpproxy.app/cli-output-formatting): Machine-readable and human-readable output formats for the MCPProxy CLI.
- [Logging](https://docs.mcpproxy.app/logging): Log file locations per OS, log levels, rotation, and per-server log files.
- [Prerelease Builds](https://docs.mcpproxy.app/prerelease-builds): Automated prerelease builds from the next branch with signed and notarized macOS installers.
- [MCP Server Registries](https://docs.mcpproxy.app/registries): The built-in set of MCP server registries used by search_servers and list_registries.
- [Tray-Core Socket Communication](https://docs.mcpproxy.app/socket-communication): Platform-specific local IPC between the tray application and the core server.