Agentic Data Plane

Test an MCP Server’s Tools with the Inspector

Verify that your MCP server’s tools, resources, and prompts work correctly before agents depend on them. The Inspector runs on the same JSON-RPC connection agents use, so a passing test means fewer failed tool calls in production. Use the Inspector after creating a server or whenever you change a tool’s schema.

After completing this guide, you will be able to:

  • Run an MCP tool from the Inspector and read its response

  • Inspect resources, prompts, and call history

  • Diagnose common errors (missing authentication, scope upgrade required, transport mismatch) before pointing an agent at the server

When to use the Inspector

  • After creating or registering a server, to confirm tool discovery completed and tools run correctly.

  • While iterating on a self-managed server, to test schema changes against a live connection.

  • When debugging an agent failure, to isolate whether the issue is in the agent or in the MCP server itself.

Open the Inspector

  1. Open MCP Servers in the sidebar and click into your server.

  2. Switch to the Inspector tab.

The Inspector has four panels: Tools, Resources, Prompts, and Session.

Tools panel

The Tools panel lists every tool the server returned from tools/list.

  1. Select a tool from the list. The right-hand pane renders a form from the tool’s input JSON schema.

  2. Fill in the form fields.

  3. Click Run. The response appears below the form.

If the tool returns an error, the response pane shows the structured error detail. See Common errors for what each common error means.

Code-mode tools

If the server has Code mode enabled, the Tools panel also lists {name}_search and {name}_execute alongside the server’s regular tools. These are the helpers an agent uses to discover and orchestrate tools through generated Python or JavaScript. Test them like any other tool.

Resources panel

The Resources panel lists any resources the server exposes through resources/list. Many MCP servers don’t expose resources at all: if the panel is empty, that’s fine.

If your server does expose resources:

  1. Click a resource to load its content into the right-hand pane.

  2. The Inspector renders text, JSON, and binary types differently; binary types show a download link.

Prompts panel

The Prompts panel lists any prompt templates the server exposes through prompts/list. Prompt templates are parameterized prompts an agent can invoke by name. As with resources, many servers don’t expose prompts.

If your server does expose prompts:

  1. Click a prompt to render its template.

  2. Fill in any required parameters in the rendered form.

  3. Click Run to see the rendered prompt content.

Session panel

The Session panel keeps a running history of every call you’ve made through the Inspector: request, response, latency. Use it to:

  • Replay a previous call by clicking it in the history list.

  • Diff two responses side-by-side (useful when iterating on a tool’s logic).

  • Copy a request as JSON-RPC for use outside the Inspector.

Common errors

Error Meaning and fix

OAuthConnectionRequired

User-delegated auth has no stored token for the calling user. Redpanda includes an authorize_url in the error detail; complete the consent flow per User-delegated OAuth.

OAuthTokenExpired

Stored token is expired and refresh failed. Re-consent through Connections.

scope_upgrade_required

The user’s connection lacks one of the server’s required_scopes. Re-consent with the higher scope.

Transport / connection error

The Inspector can’t reach the upstream. For self-managed servers, check the Connection tab on the detail page; verify the URL and transport choice.

Tool input validation error

The form’s input doesn’t match the tool’s schema. The error message includes the offending field. Update and re-run.

Test from the CLI

Use rpk ai for the same tool calls outside the UI, when scripting smoke tests or running checks from CI.

# List every tool exposed by a server
rpk ai mcp tools list <server-name>

# Call a tool with a JSON arg blob
rpk ai mcp tools call <server-name> <tool-name> --input '{"arg1":"value"}'

# Get server detail; includes the tool list by default. Add --no-tools
# to skip discovery (faster when you only want metadata).
rpk ai mcp get <server-name>

The command resolves the gateway URL from your active rpk cloud profile and reads the cached rpk cloud login token. See Connect your app to AI Gateway for installation and profile setup.

Next steps