Test MCP Server with curl

curl is one of the most widely used command-line tools for testing HTTP APIs, making it a natural choice for developers building and debugging Model Context Protocol (MCP) servers.

The good news is that yes, you can test many aspects of an MCP server using curl.

Because most MCP servers expose HTTP endpoints and communicate using JSON-RPC, curl allows you to inspect requests, validate responses, and troubleshoot problems directly from your terminal without relying on graphical tools.

However, it's important to understand that an MCP server is much more than a simple HTTP API.

A complete MCP implementation includes JSON-RPC communication, authentication, tool discovery, resources, prompts, protocol negotiation, and compatibility with AI clients such as Claude Desktop, Cursor, Windsurf, and other MCP-compatible applications.

While curl is excellent for manually sending requests and inspecting responses, it cannot automatically verify every aspect of the Model Context Protocol.

A complete MCP testing workflow should validate:

• Connectivity and transport support
• JSON-RPC communication
• Authentication and authorization
• Tool discovery
• Resource discovery
• Prompt discovery
• Error handling
• Production readiness

In this guide, you'll learn how to test an MCP server using curl, send JSON-RPC requests from the command line, validate your server's responses, understand the limitations of manual testing, and determine when it's time to use a dedicated MCP testing platform.

What Is curl?

curl is an open-source command-line utility for transferring data using a wide variety of network protocols, including HTTP and HTTPS.

It is installed by default on most Linux and macOS systems and is also available for Windows.

Developers commonly use curl to:

• Send HTTP requests
• Test REST APIs
• Inspect response headers
• Debug authentication
• Validate JSON responses
• Automate API testing in scripts and CI/CD pipelines

Because MCP servers communicate over HTTP using JSON-RPC, curl provides a fast and lightweight way to inspect server behavior without requiring additional software.

Unlike graphical API tools, curl integrates naturally into shell scripts, build pipelines, Docker containers, and automated deployment workflows.

Can You Test an MCP Server with curl?

Yes.

curl is an excellent tool for manually testing MCP servers during development.

You can use it to verify:

• JSON-RPC communication
• Authentication
• Tool discovery
• Resources
• Prompts
• Error responses
• Basic server connectivity

For developers who prefer working from the terminal, curl is often the fastest way to reproduce bugs and inspect raw server responses.

However, curl only sends requests and displays responses.

It does not understand the Model Context Protocol itself and cannot automatically validate protocol compliance, client compatibility, production readiness, or health monitoring.

Those areas require either manual verification or a dedicated MCP testing platform.

Configuring curl for MCP Testing

Before testing your MCP server, make sure it is running and accessible.

Depending on your setup, this could be:

• A local development server
• A staging environment
• A production deployment
• A publicly accessible MCP endpoint

Most MCP servers expose a single HTTP endpoint that accepts JSON-RPC requests.

For example:

http://localhost:3000/mcp

or

https://example.com/mcp

Every request should include the appropriate headers.

At a minimum:

Content-Type: application/json

If your server requires authentication, you'll also include an Authorization header or API key depending on your implementation.

Once configured, you're ready to begin sending JSON-RPC requests directly from your terminal.

Sending Your First JSON-RPC Request

Unlike traditional REST APIs, MCP servers communicate using the JSON-RPC 2.0 protocol.

Instead of sending requests to multiple endpoints, clients send structured JSON-RPC messages that describe the operation they want the server to perform.

A basic request contains four required fields:

• jsonrpc
• id
• method
• params

For example, to retrieve the list of available tools, you can send:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":1,
    "method":"tools/list",
    "params":{}
  }'

If the server is functioning correctly, it should return a valid JSON-RPC response similar to:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "createIssue",
        "description": "Create a GitHub issue"
      },
      {
        "name": "listIssues",
        "description": "List repository issues"
      }
    ]
  }
}

Receiving a successful response confirms that your server is accepting JSON-RPC requests and returning structured results.

If you receive malformed JSON, missing fields, or unexpected errors, your implementation likely requires additional debugging.

Testing Authentication

Authentication should always be validated before testing higher-level MCP functionality.

A properly configured MCP server should reject unauthenticated requests while accepting requests that include valid credentials.

Depending on your implementation, authentication may use:

• API Keys
• Bearer Tokens
• OAuth
• Session Cookies
• Custom authentication middleware

A typical Bearer token request looks like this:

curl -X POST https://example.com/mcp \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":2,
    "method":"tools/list",
    "params":{}
  }'

A useful authentication workflow is:

1. Send the request without credentials.
2. Verify that the server returns an authentication error.
3. Repeat the request using valid credentials.
4. Confirm that the request succeeds.

Typical responses include:

Without authentication:

HTTP/1.1 401 Unauthorized

With valid credentials:

HTTP/1.1 200 OK

Testing both scenarios ensures your authentication layer behaves exactly as expected.

Testing Tool Discovery

Tool discovery is one of the core capabilities of every MCP server.

AI applications use it to understand which actions they can perform.

To retrieve the available tools, send:

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0",
    "id":3,
    "method":"tools/list",
    "params":{}
  }'

Review the returned tool definitions carefully.

Each tool should include:

• Name
• Description
• Input schema
• Required parameters
• Return schema

Look for common issues such as:

• Missing descriptions
• Duplicate tool names
• Invalid JSON Schemas
• Empty parameter definitions
• Incorrect data types

Even if discovery succeeds, poorly defined metadata may still cause compatibility problems in AI clients.

Testing Resources

Resources expose structured information that AI applications can retrieve from an MCP server.

To validate resources, send the appropriate JSON-RPC request supported by your implementation.

Review the response and confirm that every resource includes:

• A valid identifier
• A valid URI
• Metadata
• Accessible content

A frequent deployment issue is exposing resources that reference missing files or unavailable services.

Testing resources with curl makes these problems much easier to identify.

Testing Prompts

Modern MCP servers often expose reusable prompts alongside tools.

Prompt discovery should verify:

• Prompt registration
• Metadata
• Variables
• Parameter definitions
• Response formatting

If prompts are incorrectly defined, AI applications may fail to display or execute them correctly even though the server itself appears healthy.

Testing prompts manually with curl helps identify these issues before deployment.

Common Mistakes When Testing MCP Servers with curl

Even experienced developers occasionally make mistakes when manually testing MCP servers.

Forgetting Required Headers

The most common issue is forgetting to include:

Content-Type: application/json

Without the correct content type, many MCP servers reject the request before processing it.

Sending Invalid JSON

Shell escaping mistakes frequently produce malformed JSON payloads.

Before debugging your server, verify that the JSON request itself is valid.

Assuming HTTP 200 Means Success

An HTTP 200 response only confirms that the HTTP request succeeded.

Always inspect the JSON-RPC response body to determine whether the requested operation actually completed successfully.

Ignoring Authentication

Many debugging sessions are caused simply by missing or incorrect authentication headers.

Always verify API keys or Bearer tokens before investigating server-side issues.

Testing Only with curl

A server that responds correctly to curl may still fail in Claude Desktop, Cursor, or other MCP clients.

curl is excellent for debugging low-level requests but should not be the only testing tool before production deployment.

Limitations of Using curl for MCP Testing

curl is one of the most powerful command-line tools for debugging HTTP APIs, but it was never designed specifically for the Model Context Protocol.

While it gives developers complete control over requests and responses, many aspects of MCP validation remain entirely manual.

Understanding these limitations helps determine when curl is sufficient and when a dedicated MCP testing platform becomes the better choice.

No Automatic Protocol Validation

curl sends exactly the request you provide.

It does not verify whether your server correctly implements the MCP specification or follows protocol best practices.

Developers must manually inspect every request and response to identify protocol violations or implementation mistakes.

No Client Compatibility Testing

Successfully receiving a JSON-RPC response does not guarantee compatibility with real AI applications.

Clients such as Claude Desktop, Cursor, and Windsurf perform additional capability negotiation and protocol validation that curl cannot simulate.

A server that works perfectly from the command line may still fail when connected to an AI client.

No Production Readiness Assessment

curl cannot answer important deployment questions such as:

• Is the server production ready?
• Are tool schemas complete?
• Are resources configured correctly?
• Does authentication behave consistently?
• Are there compatibility issues?

All of these checks must be performed manually.

No Health Monitoring

Although curl can call a health endpoint, it cannot continuously monitor:

• Availability
• Response latency
• Reliability
• Service stability

Production systems typically require automated monitoring rather than occasional manual requests.

Manual Workflow

Every validation requires manually constructing requests, managing authentication, inspecting JSON responses, and repeating the same commands after every change.

For small projects this is perfectly acceptable.

For larger production deployments, however, manual testing quickly becomes inefficient and difficult to maintain.

curl vs MCPForge

Both curl and MCPForge are valuable tools, but they solve different problems.

Rather than replacing curl, MCPForge complements it.

Many developers use curl while building an MCP server to debug individual requests and then run a complete MCPForge validation before deploying to staging or production.

When Should You Use curl?

curl is an excellent choice when you need to:

• Debug individual JSON-RPC requests
• Verify authentication headers
• Inspect raw server responses
• Test new tools during development
• Experiment with request payloads
• Automate API requests in shell scripts
• Integrate simple API checks into CI/CD pipelines

Because it is lightweight and available on almost every operating system, curl remains one of the fastest ways to troubleshoot an MCP server.

When Should You Use an MCP Testing Platform?

As an MCP server grows, manual testing becomes increasingly time-consuming.

Dedicated MCP testing platforms are better suited for:

• Production validation
• Compatibility testing
• Automated health checks
• Tool quality analysis
• Resource validation
• Prompt validation
• Security reviews
• Production readiness assessments

Instead of validating individual requests one by one, these platforms analyze the server as a complete MCP implementation and provide structured diagnostics.

Best Practices for Testing MCP Servers

Whether you prefer curl or another development tool, following a consistent testing workflow helps prevent production issues.

Recommended best practices include:

• Test authentication before validating tools.
• Verify every new tool after implementation.
• Review JSON-RPC responses for protocol compliance.
• Validate resources and prompts whenever they change.
• Monitor latency throughout development.
• Test using real MCP clients before deployment.
• Repeat validation after infrastructure or authentication changes.
• Include MCP testing in your CI/CD pipeline whenever possible.

Combining manual debugging with automated validation provides the most reliable development workflow.

Final Thoughts

curl remains one of the best command-line tools for manually testing and debugging MCP servers.

It offers complete control over HTTP requests and JSON-RPC payloads while integrating naturally into development environments, shell scripts, and automation workflows.

However, manual request testing alone is rarely enough for production deployments.

Before releasing an MCP server, it's important to verify compatibility, protocol compliance, authentication behavior, health, and overall production readiness using tools specifically designed for the Model Context Protocol.

Using curl during development and automated MCP validation before deployment gives teams the confidence to ship reliable AI integrations.

Ready to Validate Your MCP Server?

curl is ideal for debugging requests during development, but before deploying your MCP server, it's worth running a complete validation to ensure it behaves correctly across real AI clients.

The MCPForge Test MCP Server tool automatically validates:

• ✅ Connectivity and transport support
• ✅ Authentication behavior
• ✅ JSON-RPC protocol compliance
• ✅ Tool discovery
• ✅ Resource discovery
• ✅ Prompt discovery
• ✅ Health checks
• ✅ Compatibility with popular MCP clients
• ✅ Overall Production Readiness

Instead of manually inspecting every request and response, you'll receive a structured report highlighting compatibility issues, protocol violations, and recommendations for improving your server before deployment.

Ready to test your MCP server?

👉 https://www.mcpforge.tech/test-mcp-server