MCP Server is unavailable

[vv4ta783]

MCP Server doesn't work in my stirling-pdf instance. There is two problem (maybe I think).

1. Some operations return "Unknown or disabled operation: extract-pdf" on

I saw this error on

• merge-pdf
• split-pdf
• watermark-pdf
• pdf-to-word
• word-to-pdf
• extract-pdf
• delete-pdf-pages
• pdf-to-image
• image-to-pdf
• pdf-to-pdfa
• pdf-metadata
• overlay-pdf
• flatten-pdf
• get-info-on-pdf
• add-page-numbers
• repair-pdf

These Operation is available on Web UI. also I don't set any environment variable.

2. Every tool returns empty operation enum

When MCP client calls 'tools/list', returns above json

"operation": {
              "type": "string",
              "enum": [],
              "description": "Capability id from the engine manifest. Available capabilities:"
            },

This is cause of LLM cannot understand how to use tools

My environment

docker-compose.yml :

services:
  stirling-pdf:
    pull_policy: always
    image: stirlingtools/stirling-pdf:latest
    container_name: stirling-pdf
    environment:
    ports:
      - '34587:8080'
    volumes:
      - ./data/config:/configs
      - ./data/tessdata:/usr/share/tessdata
    restart: unless-stopped

Server Logs about MCP

00:22:09.309 [main] INFO  s.s.p.mcp.McpServerController - MCP server controller wired with 8 tool(s): [stirling_ai, stirling_describe_operation, stirling_convert, stirling_download, stirling_security, stirling_upload, stirling_pages, stirling_misc]
00:22:09.342 [main] INFO  s.s.p.mcp.security.McpSecurityConfig - MCP server enabled - validating configuration:
00:22:09.344 [main] INFO  s.s.p.mcp.security.McpSecurityConfig - MCP config: auth mode = apikey - clients send a Stirling API key via X-API-KEY (or Authorization: Bearer <key>); no external IdP needed. The key must belong to a provisioned, enabled account (Account -> API Keys).
00:22:12.831 [main] INFO  s.s.p.mcp.catalog.McpToolCatalog - MCP tool catalog discovered 57 PDF operation(s)
00:22:12.851 [main] INFO  s.s.p.m.e.EngineCapabilityClient - MCP engine capability refresh scheduled every 5 minute(s)
00:22:12.851 [mcp-engine-capability-refresh] INFO  s.s.p.mcp.catalog.McpToolCatalog - MCP tool catalog AI capabilities replaced: 0 entries

tools/list response json

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "stirling_ai",
        "description": "Invoke a Stirling AI agent capability (Q&A about a PDF, edit-plan generation, inline comments, math audit, draft-spec helper). Call stirling_describe_operation with the chosen capability id to get its parameters schema before invoking this tool. Some capabilities return content inline; others return a job reference that resolves to a file when ready.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "operation": {
              "type": "string",
              "enum": [],
              "description": "Capability id from the engine manifest. Available capabilities:"
            },
            "parameters": {
              "type": "object",
              "description": "Per-capability parameters.",
              "additionalProperties": true
            },
            "fileId": {
              "type": "string",
              "description": "Reference to a previously-uploaded PDF in Stirling's job store. Required for capabilities that consume a document."
            }
          },
          "required": [
            "operation"
          ]
        }
      },
      {
        "name": "stirling_describe_operation",
        "description": "Return the full JSON Schema for one Stirling operation's parameters. Call this before invoking a category tool to learn the exact shape of `parameters`. Argument: { operation: <op-id> } where <op-id> appears in the enum of any category tool (stirling_convert, _pages, _misc, _security, _ai).",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "operation": {
              "type": "string",
              "description": "Operation id (e.g. compress-pdf, pdf-to-word, q-and-a). See category tool enums."
            }
          },
          "required": [
            "operation"
          ]
        }
      },
      {
        "name": "stirling_convert",
        "description": "Convert files between PDF and other formats (PDF<->Word, PDF<->image, HTML->PDF, etc.). Inspect the `operation` enum, then call stirling_describe_operation with the chosen op to get its parameters JSON Schema before calling this tool.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "operation": {
              "type": "string",
              "enum": [],
              "description": "Operation id from this category. Call stirling_describe_operation first to learn the exact parameters schema. Available operations:"
            },
            "parameters": {
              "type": "object",
              "description": "Per-operation parameters. Schema available via stirling_describe_operation.",
              "additionalProperties": true
            },
            "file": {
              "type": "string",
              "description": "Base64-encoded file content to process. The recommended way to provide a file for most uses. Bounded by the MCP request size limit; for very large files use 'fileId' instead."
            },
            "fileName": {
              "type": "string",
              "description": "Optional original filename (with extension) for the input; helps operations that key off file type."
            },
            "fileId": {
              "type": "string",
              "description": "Reference to a file already stored via stirling_upload. Recommended only for large files or multi-step workflows; most users should pass the file inline via 'file' instead."
            }
          },
          "required": [
            "operation"
          ]
        }
      },
      {
        "name": "stirling_download",
        "description": "Fetch a stored file's content by fileId (e.g. an operation result), returned inline as base64. Recommended only when a result was too large to be returned inline. Argument: { fileId: <id> }.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "fileId": {
              "type": "string",
              "description": "Id of a stored file (e.g. an operation result's fileId)."
            }
          },
          "required": [
            "fileId"
          ]
        }
      },
      {
        "name": "stirling_security",
        "description": "Security-related PDF operations: password add/remove, redact, sanitize, certify / sign with cert, validate signature, add watermark. Call stirling_describe_operation with the chosen op to get its parameters schema before invoking this tool.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "operation": {
              "type": "string",
              "enum": [],
              "description": "Operation id from this category. Call stirling_describe_operation first to learn the exact parameters schema. Available operations:"
            },
            "parameters": {
              "type": "object",
              "description": "Per-operation parameters. Schema available via stirling_describe_operation.",
              "additionalProperties": true
            },
            "file": {
              "type": "string",
              "description": "Base64-encoded file content to process. The recommended way to provide a file for most uses. Bounded by the MCP request size limit; for very large files use 'fileId' instead."
            },
            "fileName": {
              "type": "string",
              "description": "Optional original filename (with extension) for the input; helps operations that key off file type."
            },
            "fileId": {
              "type": "string",
              "description": "Reference to a file already stored via stirling_upload. Recommended only for large files or multi-step workflows; most users should pass the file inline via 'file' instead."
            }
          },
          "required": [
            "operation"
          ]
        }
      },
      {
        "name": "stirling_upload",
        "description": "Store a file server-side and get back a fileId to reuse across operations. Recommended only for large files or multi-step workflows; for a single operation on a typical file, pass the file inline via the operation's `file` argument instead. Argument: { file: <base64>, fileName?: <name> }.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "file": {
              "type": "string",
              "description": "Base64-encoded file content."
            },
            "fileName": {
              "type": "string",
              "description": "Optional original filename (with extension)."
            }
          },
          "required": [
            "file"
          ]
        }
      },
      {
        "name": "stirling_pages",
        "description": "Manipulate PDF pages: merge, split, rotate, rearrange, crop, delete, overlay, add blank pages. Call stirling_describe_operation with the chosen op to get its parameters schema before invoking this tool.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "operation": {
              "type": "string",
              "enum": [],
              "description": "Operation id from this category. Call stirling_describe_operation first to learn the exact parameters schema. Available operations:"
            },
            "parameters": {
              "type": "object",
              "description": "Per-operation parameters. Schema available via stirling_describe_operation.",
              "additionalProperties": true
            },
            "file": {
              "type": "string",
              "description": "Base64-encoded file content to process. The recommended way to provide a file for most uses. Bounded by the MCP request size limit; for very large files use 'fileId' instead."
            },
            "fileName": {
              "type": "string",
              "description": "Optional original filename (with extension) for the input; helps operations that key off file type."
            },
            "fileId": {
              "type": "string",
              "description": "Reference to a file already stored via stirling_upload. Recommended only for large files or multi-step workflows; most users should pass the file inline via 'file' instead."
            }
          },
          "required": [
            "operation"
          ]
        }
      },
      {
        "name": "stirling_misc",
        "description": "Miscellaneous PDF operations: compress, OCR, stamp / watermark, edit metadata, flatten, repair, and similar utilities. Call stirling_describe_operation with the chosen op to get its parameters schema before invoking this tool.",
        "inputSchema": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "operation": {
              "type": "string",
              "enum": [],
              "description": "Operation id from this category. Call stirling_describe_operation first to learn the exact parameters schema. Available operations:"
            },
            "parameters": {
              "type": "object",
              "description": "Per-operation parameters. Schema available via stirling_describe_operation.",
              "additionalProperties": true
            },
            "file": {
              "type": "string",
              "description": "Base64-encoded file content to process. The recommended way to provide a file for most uses. Bounded by the MCP request size limit; for very large files use 'fileId' instead."
            },
            "fileName": {
              "type": "string",
              "description": "Optional original filename (with extension) for the input; helps operations that key off file type."
            },
            "fileId": {
              "type": "string",
              "description": "Reference to a file already stored via stirling_upload. Recommended only for large files or multi-step workflows; most users should pass the file inline via 'file' instead."
            }
          },
          "required": [
            "operation"
          ]
        }
      }
    ]
  }
}

[Frooodle]

Greatly appreciate all the logs and details here!

We have been improving MCP for our upcoming release so will check against these and confirm for you if it's been fixed

[vv4ta783]

Thanks for reply!
I'm looking forward to receive update!