@capsulesecurity/capsule-mcp-server

An MCP server that lets any MCP-compatible AI client query a Capsule tenant.

It runs locally over stdio and authenticates as a Capsule service account using the OAuth 2.0 client_credentials grant. Access is read-only and scoped to the single tenant that owns the service account.

Setup

Create a service account in Capsule under Settings > Service Accounts. The client secret is shown only once, at creation time.

{
  "mcpServers": {
    "capsule": {
      "command": "npx",
      "args": ["-y", "@capsulesecurity/capsule-mcp-server"],
      "env": {
        "CAPSULE_CLIENT_ID": "<client id>",
        "CAPSULE_CLIENT_SECRET": "<client secret>"
      }
    }
  }
}

| Variable | Required | Default | | ----------------------- | -------- | ------------------------------------------------ | | CAPSULE_CLIENT_ID | yes | - | | CAPSULE_CLIENT_SECRET | yes | - | | CAPSULE_API_URL | no | https://portal.us-east1.capsulesecurity.io/api |

CAPSULE_API_URL selects the regional deployment. It defaults to US (us-east1); EU tenants must set it to https://portal.eu-west4.capsulesecurity.io/api. It must be https, except on localhost/127.0.0.1 for local development.

Tools

describe_type returns the GraphQL SDL for any type, input, or enum. The schema is bundled into the package, so the package version pins the schema version.

query_graphql runs a read-only GraphQL query. Queries are parsed and validated against the bundled schema before they are sent, which is what makes wrong field names come back as specific, correctable errors - Capsule replaces GraphQL error detail with a generic message in production. Non-query operations are rejected, and large results are trimmed with a __truncated marker carrying the original count.

Access model

A service account can read everything the VIEWER role permits within its own tenant. There is no finer-grained control: no per-tool scopes, and no way to grant one connected client less access than another. Session and activity message bodies are redacted for VIEWER, so this server can read security metadata but not raw prompt or tool-output text.

Requests are limited to 60 per minute per service account, so give each connected client its own account rather than sharing one.

Everything above is enforced by the Capsule API. The package runs on the user's machine and is therefore untrusted - nothing it does locally is a security control.

Rotating and revoking credentials

A service account holds up to two active secrets, so a new one can be added and the configuration updated before the old one is revoked.

Revoking a secret stops new access tokens from being issued immediately, but a token already issued stays valid until it expires, within 15 minutes. Delete the service account to cut access off without waiting.

Local development

pnpm nx run mcp-server:build
pnpm nx run mcp-server:test

Point a client at the local build with an absolute path instead of npx, and set CAPSULE_API_URL to http://localhost:4000/api:

{
  "mcpServers": {
    "capsule": {
      "command": "node",
      "args": ["<repo>/libs/mcp-server/dist/index.js"],
      "env": {
        "CAPSULE_CLIENT_ID": "<client id>",
        "CAPSULE_CLIENT_SECRET": "<client secret>",
        "CAPSULE_API_URL": "http://localhost:4000/api"
      }
    }
  }
}

Publishing

Published to npm as @capsulesecurity/capsule-mcp-server. Releases are cut by hand for now, from a clean checkout of main:

pnpm nx run mcp-server:build
cd libs/mcp-server && pnpm publish --access public

Bump the version in package.json and SERVER_VERSION in src/server.ts together. The GraphQL schema is bundled at build time, so the published version pins the schema version and a schema change needs a release to reach clients.