Troubleshoot Remote MCP Servers

This page helps you diagnose and fix common issues when building and running Remote 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 deploying. The Cloud Console provides a Lint button that validates your YAML.

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..."
  }
}

Contact Redpanda support if you see this error in Redpanda Cloud.

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:

    • Verify the MCP server status shows Running in the Cloud Console.

    • Check the Logs tab for any startup errors.

  3. Verify correct directory structure:

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.

  4. Review the Logs tab in the Cloud Console for error messages.

Connection issues

MCP client can’t connect to server

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

  1. Verify authentication:

    • Run rpk cloud login to refresh your authentication token.

    • Tokens expire after 1 hour.

  2. Check the MCP proxy configuration:

    • Verify the cluster ID and MCP server ID are correct.

    • Run rpk cloud mcp proxy --help to see available options.

  3. Verify the MCP server is running:

    • Check the server status in the Cloud Console.

    • Review the Logs tab for startup errors.

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. Check if the MCP server is being restarted due to resource limits. Consider scaling up resources.

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 using the Lint button in the Cloud Console.

  2. Test tool logic using the MCP Inspector.

  3. Connect to your AI client using rpk cloud mcp proxy.

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

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:

For protocol-level troubleshooting, see the MCP documentation.