MCP Server

Connect AI assistants to Stirling PDF through its built-in Model Context Protocol (MCP) server. MCP is disabled by default.

Enable the server#

Enable MCP in the MCP Server section of Settings → Server → Integrations, or with one of the methods below. Configure authentication, then restart the server. Without login enabled, use the settings file or environment variables.

mcp:
  enabled: true
  scopesEnabled: true
  auth:
    mode: oauth
    issuerUri: 'https://idp.example.com'
    resourceId: 'https://pdf.example.com/mcp'
    acceptedAudiences: ['authenticated']
    usernameClaim: email
    requireExistingAccount: true

MCP_ENABLED=true
MCP_SCOPESENABLED=true
MCP_AUTH_MODE=oauth
MCP_AUTH_ISSUERURI=https://idp.example.com
MCP_AUTH_RESOURCEID=https://pdf.example.com/mcp
MCP_AUTH_ACCEPTEDAUDIENCES=authenticated
MCP_AUTH_USERNAMECLAIM=email
MCP_AUTH_REQUIREEXISTINGACCOUNT=true

services:
  stirling-pdf:
    environment:
      MCP_ENABLED: "true"
      MCP_SCOPESENABLED: "true"
      MCP_AUTH_MODE: oauth
      MCP_AUTH_ISSUERURI: https://idp.example.com
      MCP_AUTH_RESOURCEID: https://pdf.example.com/mcp
      MCP_AUTH_ACCEPTEDAUDIENCES: authenticated
      MCP_AUTH_USERNAMECLAIM: email
      MCP_AUTH_REQUIREEXISTINGACCOUNT: "true"

The limit settings are available through the settings file or environment variables.

Endpoint#

• Endpoint: POST /mcp, same host and port as the rest of Stirling PDF. Consumes and produces application/json.
• Transport: JSON-RPC 2.0 over streamable-HTTP only.
• Supported MCP protocol versions: 2025-06-18 (preferred), 2025-03-26, 2024-11-05.
• Desktop clients in Self-hosted mode use the /mcp endpoint of the server they point at.

Tools exposed#

Operation ids are the same kebab-case ids used elsewhere in Stirling PDF (for example compress-pdf); /api/v1/filter/* and /api/v1/pipeline are not exposed over MCP.

Calling a tool#

Arguments for stirling_pages, stirling_convert, stirling_misc, stirling_security (stirling_ai differs, see AI capabilities):

Use stirling_describe_operation to find the required parameters and scope before calling an operation.

• A JSON response from the operation is returned as text.
• File results up to mcp.maxInlineResponseBytes return inline as base64 (stirling://file/{fileId}) with their fileId.
• Larger results return only a fileId. Pass it to another operation, or raise mcp.maxInlineResponseBytes to fetch it with stirling_download.

{"name": "stirling_download", "arguments": {"fileId": "abc123"}}

AI capabilities#

Set up the AI engine to use stirling_ai. The engine must be enabled and reachable from Stirling PDF.

Calling stirling_ai#

Supply operation and a parameters object matching the capability's schema, including its document reference.

Use mcp.allowedOperations and mcp.blockedOperations to control AI access over MCP. The Capabilities switches in Settings → Server → AI Engine apply to the app's tools.

For MCP compatibility, leave STIRLING_REQUIRE_USER_ID set to false on the engine.

Authentication#

Scopes#

PDF operations and uploads require mcp.tools.write; downloads require mcp.tools.read. AI scopes are listed above. Set mcp.scopesEnabled: false to disable scope checks. Scopes apply only in OAuth mode.

OAuth2 resource server (oauth, default)#

Configure issuerUri and at least one audience through resourceId or acceptedAudiences.

RFC 9728 protected-resource metadata is published at /.well-known/oauth-protected-resource in OAuth mode only. GET on that path is unauthenticated so clients can discover the authorization server.

API key (apikey)#

Set mcp.auth.mode: apikey (env MCP_AUTH_MODE=apikey) and clients authenticate with an existing per-user Stirling API key. No external IdP, OAuth, or JWKS configuration is needed.

Send the key as either header:

X-API-KEY: <your-stirling-api-key>
Authorization: Bearer <your-stirling-api-key>

Generate a key under Settings → Preferences → API Keys while signed in. The key must belong to an enabled account; missing or invalid keys return HTTP 401. See API documentation.

Restrict which operations are exposed#

Both lists use the same kebab-case operation ids as Endpoint or Feature Customisation.

Both lists apply to PDF operations and to AI capabilities. In the admin UI the fields accept ids separated by commas, spaces, or newlines.

PDF operations disabled through Endpoint Customisation are also unavailable over MCP.

Limits#

Troubleshooting#

• Client cannot connect: check the endpoint, authentication settings, and server startup log.
• 401 with error="invalid_token": the error_description names the cause (audience, issuer, or expiry mismatch).
• Behind a reverse proxy, set X-Forwarded-Proto, X-Forwarded-Host and X-Forwarded-Port correctly so the resource_metadata pointer is right.
• 403 insufficient_account: check that the configured username claim matches an enabled Stirling user.
• 413 payload_too_large: the request body exceeded mcp.maxRequestBytes. Switch large inputs from inline file to stirling_upload plus fileId.

Connect a client#

Point any MCP client at http://your-host:8080/mcp (use your real host, port, and scheme).

MCP Inspector:

npx @modelcontextprotocol/inspector

Set the transport to streamable-HTTP and the URL to your /mcp endpoint, adding the auth header (X-API-KEY in API-key mode, or a Bearer token in OAuth mode).

Claude Desktop via the mcp-remote bridge:

{
  "mcpServers": {
    "stirling-pdf": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://your-host/mcp",
        "--header",
        "X-API-KEY:your-stirling-api-key"
      ]
    }
  }
}

In OAuth mode, drop the X-API-KEY header and let mcp-remote complete the OAuth flow against your configured issuer.

Related Documentation#

• API documentation
• Endpoint Customisation
• AI Security