External MCP Connector
The External MCP connector mounts a third-party (or self-hosted) MCP server inside ApexMCP. Agents call ApexMCP using your standard API key; ApexMCP forwards the call to the target MCP server, applies governance, and returns the result.
You get auth, audit, rate-limiting, and credential isolation in front of any MCP server — without changing the upstream server, and without exposing its credentials to agents.
Why use it
- One API key per agent — revoke or scope an agent without rotating credentials on every upstream MCP server.
- Central audit log — every tool call is logged with org, connector, tool, status, latency in
request_logs. Useful for SOC 2 / GDPR audit trails. - Per-org rate-limits — same Redis-backed quota that protects in-house tools also protects the proxied server.
- Credential injection — the upstream server’s bearer token / OAuth token lives in the credential vault. Agents never see it.
- Per-tool blocklist — disable individual tools on the upstream server without redeploying it (e.g. hide
delete_*tools for read-only agents).
How it works
- Agent calls ApexMCP gateway:
tools/callwith a namespaced namemyslug.toolname. - ApexMCP looks up the External MCP connector by slug, verifies the agent’s scope (
mcp:callormcp:call:<connector-id>). - ApexMCP forwards the call to the configured
target_urlusing the credentials stored in the vault. - Response streams back to the agent. Audit row written, quota incremented.
The agent must use the slug-prefixed tool name. This is intentional — one ApexMCP endpoint can multiplex many backends behind a single agent connection.
Configuration
In Connectors → New Connector → External MCP:
| Field | Description |
|---|---|
| Name | Display name. The slug is derived from this (sanitised lowercase). |
| Target URL | The upstream MCP server’s URL (HTTPS, JSON-RPC). |
| Credentials | Bearer token / API key / OAuth token used by ApexMCP when calling the upstream. Stored encrypted in the credential vault. |
| Disabled tools | Optional list of tool names to hide from agents. Hidden tools return -32601 Tool not found. |
Scoping an agent to one external MCP
Use the same scope format as in-house connectors:
mcp:call:<connector-id>The token can only call tools whose slug matches that connector. Everything else returns -32003 Insufficient scope.
Quota and 429s
External MCP calls count against the same per-org tool-call quota as in-house tool calls. When the org quota is exhausted, the call returns RPC error code -32000 with message API quota exceeded. Upgrade your plan to continue. and is logged with status 429.
Failure modes
| Upstream returns | ApexMCP returns |
|---|---|
| 2xx with JSON-RPC result | result forwarded as-is |
| 2xx with JSON-RPC error | error code + message forwarded |
| Non-2xx HTTP | RPC error code -32603, status 502 audited |
| Timeout | RPC error code -32603, message timeout |
Limitations
- Streaming MCP transports beyond standard JSON-RPC over HTTP are not yet bridged transparently.
- The upstream server must be reachable from the ApexMCP gateway egress IPs.
- Tool list is cached per connector; refresh via Connectors → [name] → Refresh Schema.