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 a server’s resources, prompts, and session activity

  • 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 is a console: a tool list and a tool runner sit side by side, with a status strip along the top. Resource and prompt panels appear underneath only when the server exposes those capabilities. Two more surfaces open from the status strip: Session details and the Protocol panel. See Review session and protocol details for both.

MCP Inspector flow. The Inspector identifies the server’s MCP version and capabilities, discovers tools, resources, and prompts, sends a selected tool call as JSON-RPC, and shows the formatted result beside the wire frames, timing, progress, and errors.
Figure 1. The MCP Inspector follows one request from discovery through the protocol view

Run a tool

The tool list shows every tool the server returned from tools/list. When a server exposes more than one tool, a filter box narrows the list by tool name, title, or description, and shows a count of how many tools match. Long tool names wrap in full instead of being cut off. Select a tool to load it into the runner.

  1. Select a tool from the list. The runner shows the tool’s input and, after you run it, its response.

  2. Provide the tool’s input using one of the input modes:

    • Form: A field-by-field form generated from the tool’s input JSON schema.

    • JSON: The raw JSON input, for pasting or editing a whole object at once.

    • cURL: A ready-to-run curl command for the call, with a copy action.

  3. Click Run tool, or press Ctrl+Enter (Cmd+Enter on macOS). While the call is in flight, a progress bar reflects any progress the server reports, and you can Cancel it.

The response appears in a tabbed result card:

  • Result: The tool’s output. Toggle between Formatted (pretty-printed JSON) and Raw (the exact response text).

  • Raw JSON-RPC: The reconstructed request and response envelopes, with the method and parameters exactly as the server sees them.

  • Output schema: The tool’s declared output schema, shown when the tool provides one.

A status indicator reports whether the call succeeded and how long it took. Copy actions let you copy the input, the output, or the JSON-RPC envelope. If the tool returns an error, the result card 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 tool list also includes {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.

Inspect resources

When the server exposes resources through resources/list, a Resources panel appears below the runner. Many MCP servers don’t expose resources at all: if there’s no panel, that’s fine.

If your server does expose resources:

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

  2. The Inspector renders text, JSON, and binary types differently; for a binary payload, it reports the size and tells you to decode the content with a client SDK.

Inspect prompts

When the server exposes prompt templates through prompts/list, a Prompts panel appears below the runner. 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.

Review session and protocol details

The status strip along the top of the console shows the connection status and how many tool calls you’ve made this session, along with two controls:

Session details opens a side panel with the session’s connection health, negotiated capabilities, and protocol version. Use it to confirm the Inspector connected and to see which capabilities (tools, resources, prompts) the server advertised.

Protocol panel opens a panel next to the runner:

  • Wire: The JSON-RPC request and result frames for your calls, any notifications the server sends, and a timing breakdown of the most recent call.

  • Timeline: A running log of the calls you’ve made this session, each with its result and latency.

  • Logs: Log lines the server sends over MCP logging.

A telemetry strip reports the last call’s latency, time to first byte, payload size, and estimated context tokens. Click Clear to empty these views.

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 My 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-server tools list <server-name>

# Call a tool with a JSON arg blob
rpk ai mcp-server 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-server get <server-name>

The command targets the AI Gateway of your selected Agentic Data Plane environment, using credentials from rpk ai auth login. See Connect your app to AI Gateway for installation and sign-in.

Next steps