MCP API

Authentication

All MCP endpoints require Admin or above — MCP servers grant agents real capabilities and misconfiguration can have broad impact, so management is admin-only.

Catalogue

GET /api/mcp/catalog

Browse the curated MCP catalogue — ~35 community MCP servers pre-vetted and kept current.

Query parameters:

Response: an array of catalogue entries. Each entry includes id, name, description, category, transport (stdio / http / sse), runtime requirements (node / python / pipx / none), verified-by flag, and install instructions.

GET /api/mcp/catalog/{id}

Get a specific catalogue entry in detail, including its full manifest and any required environment variable specifications.

Response: the full catalogue entry object.

Runtime detection

GET /api/mcp/runtime

Check which MCP runtimes are detected on the Exolvra host. Use this before trying to install a stdio MCP server that requires Node or Python.

Response:

{
  "node": {
    "detected": true,
    "version": "v22.14.0",
    "path": "/usr/local/bin/node"
  },
  "python": {
    "detected": true,
    "version": "3.12.2"
  },
  "pipx": {
    "detected": false
  }
}

If a runtime you need is missing, see MCP setup for install instructions.

Installed servers

GET /api/mcp/installed

List all MCP servers currently installed on this instance.

Response: an array of installed server objects. Each includes id, name, catalogue id it was installed from, transport, status (enabled / disabled / error), last verification result, and timestamps.

Credentials are never returned in responses — they live encrypted at rest and are only decrypted in-memory when calls are made out to the server.

GET /api/mcp/installed/{id}

Get a single installed server by id.

Response: the installed server object.

POST /api/mcp/installed

Install a new MCP server from the catalogue.

Request body:

{
  "catalogId": "github-mcp",
  "envValues": {
    "GITHUB_TOKEN": "ghp_..."
  }
}

Response: 201 Created with the new installed server object. The env values are encrypted before persistence.

PUT /api/mcp/installed/{id}

Update an installed server — usually to change its configuration or update credentials.

Request body: fields to update (typically envValues). Omit fields you don’t want to change.

Response: the updated server object.

POST /api/mcp/installed/{id}/verify

Test whether an installed MCP server is reachable and responding. For stdio servers, this spawns the subprocess and checks it responds to the MCP handshake. For HTTP servers, this makes a health request to the endpoint.

Response:

{
  "status": "ok",
  "details": "Server responded in 347 ms",
  "capabilities": ["read_file", "write_file", "execute_query"]
}

Or, on failure:

{
  "status": "error",
  "details": "Runtime not detected: Node.js required but not found in PATH"
}

POST /api/mcp/installed/{id}/enable

Enable a previously-disabled MCP server. Agents granted access can invoke its tools again on their next turn.

Response: 204 No Content.

DELETE /api/mcp/installed/{id}

Uninstall an MCP server. Subprocess (for stdio) is terminated, encrypted credentials are wiped, and per-agent access entries are removed.

Response: 204 No Content.

Per-agent access

MCP servers use explicit per-agent access control — installing a server doesn’t automatically grant any agent access. You have to enable it for each agent that should use it.

GET /api/mcp/installed/{id}/access

Get the current access list for a specific MCP server.

Response: an array of entries, one per agent, with a boolean showing whether that agent is granted access.

[
  { "agentId": "research-analyst", "granted": true },
  { "agentId": "code-assistant", "granted": false },
  { "agentId": "project-manager", "granted": true }
]

PUT /api/mcp/installed/{id}/access

Update the access list for a specific MCP server.

Request body: an array of {agentId, granted} objects. Agents omitted from the array keep their current access; agents included with granted: false are revoked.

{
  "entries": [
    { "agentId": "research-analyst", "granted": true },
    { "agentId": "code-assistant", "granted": true }
  ]
}

Response: the updated access list.

Example — install and grant a GitHub MCP server

# Verify Node is available
curl https://your-exolvra.example/api/mcp/runtime \
  -H "Authorization: Bearer exou_..."

# Browse the catalogue
curl "https://your-exolvra.example/api/mcp/catalog?category=dev" \
  -H "Authorization: Bearer exou_..."

# Install the GitHub MCP server
curl -X POST https://your-exolvra.example/api/mcp/installed \
  -H "Authorization: Bearer exou_..." \
  -H "Content-Type: application/json" \
  -d '{
    "catalogId": "github-mcp",
    "envValues": { "GITHUB_TOKEN": "ghp_abc123..." }
  }'

# Verify it works
curl -X POST https://your-exolvra.example/api/mcp/installed/github-mcp/verify \
  -H "Authorization: Bearer exou_..."

# Grant access to the code-assistant agent
curl -X PUT https://your-exolvra.example/api/mcp/installed/github-mcp/access \
  -H "Authorization: Bearer exou_..." \
  -H "Content-Type: application/json" \
  -d '{"entries": [{"agentId": "code-assistant", "granted": true}]}'

The code-assistant agent now has GitHub tools in its tool set and can use them on its next turn.

Common pitfalls

Sending credentials in plaintext. Always use HTTPS when calling the install endpoint — credentials are encrypted at rest, but they travel in cleartext in the request body. If your gateway isn’t behind HTTPS, any call that passes secrets is exposed.

Trying to install a stdio MCP without its runtime. If Node or Python isn’t detected, the install will fail. Check /api/mcp/runtime first and install the missing runtime (MCP setup) before retrying.

Forgetting per-agent access after install. Installation is step one; granting is step two. An MCP server that’s installed but not granted to any agent is dead weight — no agent can call its tools.

Where to go next

• MCP Library — the dashboard counterpart
• MCP setup — install Node / Python for stdio MCPs
• Tools, skills & MCP — the conceptual model