Troubleshoot MCP Servers

This page helps you diagnose and fix common issues when building and running MCP servers.

Use this page to:

  • Diagnose and fix lint and YAML configuration errors

  • Resolve runtime issues when tools don’t appear or return unexpected results

  • Debug client connection problems

Lint errors

Always lint your configuration before starting the server:

rpk connect mcp-server lint

Common lint errors

  • unable to infer component type: Your file contains multiple component types or uses wrapper blocks. Each YAML file must contain only a single component type and should not be wrapped in an input: or output: block. See Unable to infer component type.

  • unknown field: A configuration field is misspelled. Check the field name against the component documentation.

  • missing required field: A required field is missing from your configuration. Add the missing field.

Unable to infer component type

If you see errors like the following, your YAML file contains more than one component type or uses a wrapper:

resources/inputs/redpanda-consume.yaml(1,1) unable to infer component type: [input processors cache_resources meta]
resources/outputs/redpanda-publish.yaml(1,1) unable to infer component type: [processors output meta]

To fix this, split out each component type into its own file.

Incorrect: Multiple component types
label: incorrect-example
input:
  redpanda: { ... }
processors:
  - mutation: { ... }
output:
  redpanda: { ... }
Correct: Single component type
label: event-reader
redpanda:
  seed_brokers: [ "${REDPANDA_BROKERS}" ]
  topics: [ "events" ]
  consumer_group: "mcp-reader"
meta:
  mcp:
    enabled: true
    description: "Consume events from Redpanda"

JSON schema errors

JSON schema errors indicate that you’re using an outdated version of Redpanda Connect with an incompatible JSON schema format:

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "tools.17.custom.input_schema: JSON schema is invalid..."
  }
}

Upgrade to at least version 4.66.1 of Redpanda Connect:

rpk connect --version

If you need to upgrade, see Upgrade Redpanda Connect.

Runtime issues

Tool not appearing in MCP client

If your tool doesn’t appear in the MCP client’s tool list:

  1. Verify that meta.mcp.enabled: true is set in your YAML configuration.

  2. Check the tool has the correct tag:

    • Ensure the tool’s meta.tags array includes the tag you specified when starting the server.

    • Example: If you started with --tag bluesky, your tool needs tags: [ bluesky ].

  3. Verify correct directory structure:

    • Processors: resources/processors/

    • Inputs: resources/inputs/

    • Outputs: resources/outputs/

    • Caches: resources/caches/

Example correct structure
label: my-tool
# ... component configuration ...
meta:
  tags: [ my-tag ]  # Must match --tag argument
  mcp:
    enabled: true   # Required for exposure
    description: Tool description

Tool returns unexpected results

If your tool runs but returns unexpected data:

  1. Check input validation. Add logging to see what inputs the tool receives:

    - log:
    message: "Received input: ${! json() }"
    level: DEBUG

  2. Verify data transformations. Log intermediate results between processors.

  3. Check external API responses. The API may return different data than expected.

Connection issues

MCP client can’t connect to server

If your MCP client can’t connect to your local MCP server:

  1. Verify the server is running:

    • Check that the MCP server process is still running in your terminal.

    • Look for "Registering processor tool" log messages at startup.

    • Confirm the server is listening on the expected address (default: localhost:4195).

  2. Check for port conflicts:

    If port 4195 is already in use, specify a different port:

    rpk connect mcp-server --address localhost:4196 --tag my-tag

    Then update your mcp-remote connection:

    claude mcp add local -- npx mcp-remote http://localhost:4196/sse

  3. Verify the SSE endpoint:

Connection drops or times out

If connections are unstable:

  1. Check network connectivity between the client and server.

  2. Verify no firewall rules are blocking the connection.

  3. Ensure the MCP server process isn’t being killed by the OS (check system logs).

Debugging techniques

Use these techniques to systematically isolate and fix issues with your MCP tools.

Add temporary logging

Insert log processors to debug data flow:

processors:
  - log:
      message: "Input received: ${! json() }"
      level: DEBUG
  - # ... your processing logic ...
  - log:
      message: "Output produced: ${! json() }"
      level: DEBUG

The ${! json() } syntax uses Bloblang interpolation to insert the current message content.

Remove debug processors before deploying to production.

Test your tools

Build confidence by testing at each stage:

  1. Lint your configuration with rpk connect mcp-server lint.

  2. Start the server and test with cURL or an MCP client.

  3. Connect to your AI client and verify the tool appears.

  4. Test end-to-end with realistic prompts.

For the complete testing workflow with cURL scripts, see Test the tool.

Isolate the problem

When debugging complex tools:

  1. Test each processor individually by commenting out others.

  2. Use static test data instead of live API calls.

  3. Check if the issue is in input validation, processing logic, or output formatting.

  4. Compare working tools with broken ones to identify differences.

Next steps

If you’re still experiencing issues: