How to Test MCP Servers

There are two main ways to run an MCP test: locally on a development machine, or remotely over the network.

Local testing is typically faster and allows direct debugging. Remote testing is useful when the server is deployed in a hosted environment. This article starts with how to set up a local test environment, followed by strategies for remote testing, security setup, and debugging.

Setting up a local test environment

Local testing of an MCP server requires Node.js (>= v18), access to your MCP server code, and optionally Python if your server uses it. The MCP Inspector is the main server tester tool for running MCP tests. It works with both local and remote servers and supports multiple transport methods.

To get started, you'll need:

• Node.js (version 18.0.0 or higher)

• npx (included with Node.js)

• Your MCP server code

The simplest way to test a local MCP server is using the Inspector with npx:

npx @modelcontextprotocol/inspector node

This command starts your server and launches the Inspector interface in your browser. The Inspector connects to your server, lists its available tools, and lets you test them interactively.

For more complex setups, you can create a configuration file that defines how to launch your server:

{
  "mcpServers": {
    "my-server": {
      "command": "node",
      "args": ["build/index.js"],
      "env": {
        "API_KEY": "your-api-key"
      }
    }
  }
}

Then run the Inspector with this config:

npx @modelcontextprotocol/inspector --config ./mcp.json --server

The Inspector UI opens at http://localhost:6274 by default. From there, you can:

• View all tools exposed by your server

• Test tools by entering parameters and viewing results

• Check server logs and error messages

• Validate tool schemas

Testing tools with the Inspector

The Inspector provides a visual interface for testing MCP tools. When you open the Inspector, you'll see several tabs for different aspects of your server.

The Tools tab shows all available tools with their schemas and descriptions. To test a tool:

1. Select a tool from the list

2. Enter valid input parameters in the form

3. Click "Run" to execute the tool

4. View the result in the response panel

For example, if your server has a "weather" tool that takes a location parameter, you would:

• Select the "weather" tool

• Enter a location like "San Francisco"

• Click "Run"

• See the weather data in the response

The Inspector also shows any errors that occur during tool execution. Common errors include:

• Missing required parameters

• Invalid parameter types

• Server-side execution errors

By testing tools through the Inspector, you can verify that your MCP server correctly handles inputs, executes tools, and returns properly formatted results.

Testing remote MCP servers

Testing remote MCP servers requires additional steps since many LLM clients can't directly connect to remote URLs. The solution is to use a proxy that connects your local client to the remote server.

The most common approach is using the mcp-remote package:

This creates a local proxy that forwards requests to your remote server. You can then connect LLM clients like Claude Desktop to this proxy.

To connect Claude Desktop to a remote server:

1. Open Claude Desktop

2. Go to Settings → Developer → Edit Config

3. Add this configuration:

{
  "mcpServers": {
    "remote-server": {
      "command": "npx",
      "args": ["mcp-remote", "https://your-server.example.com/sse"]
    }
  }
}

4. Save and restart Claude

This setup tells Claude to launch the mcp-remote proxy and connect to your remote server. When Claude loads, it will show the tools from your remote server.

For other clients like Cursor, use a similar approach but follow their specific configuration format. Most clients support launching commands to connect to servers.

Security considerations for testing

When testing MCP servers, security is important, especially when working with real data or production systems. The MCP Inspector includes several security features:

• Session tokens: The Inspector generates a random token that must be included in requests

• Local-only binding: By default, the Inspector only accepts connections from localhost

• Origin validation: The server checks request origins to prevent cross-site attacks

These features help protect your server during testing. For local development, the default settings are usually sufficient. For remote testing, additional precautions may be needed.

If you're testing with sensitive data:

• Use environment variables for credentials instead of hardcoding them

• Avoid exposing development servers to the public internet

• Use temporary tokens that expire after testing

The server tester tools like Inspector handle most security concerns automatically, but it's good to understand these protections when setting up test environments.

Debugging common MCP server issues

When your MCP test fails, there are several common issues to check:

Connection problems

If the Inspector can't connect to your server:

• Verify the server is running

• Check that ports aren't blocked by firewalls

• Ensure the transport method (STDIO, SSE, HTTP) is correctly specified

Schema validation errors

If tools appear but fail to execute:

• Look for missing required parameters

• Check parameter types match the schema

• Verify complex schemas are correctly resolved

Authentication failures

If requests are rejected:

• Confirm the session token is included in requests

• Check that environment variables are correctly passed

• Verify the server accepts the client's origin

The Inspector shows detailed error messages that help identify these issues. For deeper debugging, enable verbose logging with:

DEBUG=true npx @modelcontextprotocol/inspector node

This shows all messages exchanged between the client and server, making it easier to spot where things go wrong.

Handling large APIs and complex schemas

Testing MCP servers with large APIs presents unique challenges. When an API has hundreds of endpoints, trying to test them all at once can be overwhelming.

Some strategies for testing large APIs:

• Test tools in groups: Focus on related tools that work together

• Selective loading: Configure your server to expose only specific tools during testing

• Progressive testing: Start with simple tools and gradually add more complex ones

Complex schemas with nested structures or recursive references can also be challenging. The MCP Inspector handles most schema complexities automatically, but there are limits:

• Some LLM clients have maximum schema sizes

• Deeply nested schemas may be truncated

• Recursive references must be resolved to a finite depth

When testing complex schemas, check that tools are correctly displayed in the Inspector and that parameters are properly validated. If a schema is too complex, consider simplifying it or breaking it into smaller pieces.

Testing MCP servers next steps

Testing MCP servers is an evolving practice as the protocol itself continues to develop. After mastering basic testing with the Inspector, you might explore:

• Automated testing using the Inspector's CLI mode

• Integration testing with actual LLM clients

• Performance testing for high-traffic scenarios

At Stainless, we've built tools that automatically generate MCP servers from OpenAPI specifications. This approach handles many common challenges like schema transformation, reference resolution, and tool naming. Our experience has shown that proper testing is essential for creating reliable MCP servers that integrate smoothly with LLMs.

Whether you're building MCP servers from scratch or generating them from existing APIs, thorough testing ensures they work correctly with all clients and handle edge cases properly.

Frequently asked questions about MCP testing

How do I test an MCP server without exposing it to the internet?

Use the MCP Inspector locally with npx @modelcontextprotocol/inspector node server.js. This runs everything on your local machine without requiring external access.

What tools can verify if my MCP server correctly implements the protocol?

The MCP Inspector is the primary server tester tool for protocol verification. It validates schemas, tests tool execution, and checks response formats to ensure compliance.

How can I test specific endpoints in my MCP server?

Configure your server to expose only the tools you want to test, or use the Inspector's tool selection interface to focus on specific tools during testing.

Why might my MCP server work with one client but not another?

Different LLM clients have varying schema limitations and protocol implementations. Test with multiple clients to ensure compatibility, and simplify complex schemas if needed.