Testing and Debugging MCP Servers with the MCP Inspector

The MCP Inspector is a powerful tool for validating, testing, and debugging MCP servers. This hands-on guide walks you through using the Inspector to verify your MCP server is working correctly and troubleshoot common issues.

What is the MCP Inspector?

The MCP Inspector is a debugging tool that allows you to:

Connect directly to an MCP server
List available tools and resources
Make test tool calls
View request/response payloads
Debug authentication issues
Validate server responses

Getting the MCP Inspector

The MCP Inspector is typically available as:

A command-line tool
A web-based interface
Part of MCP development tools

Check the official MCP documentation for the latest Inspector tool and installation instructions.

Step 1: Connect to Your MCP Server

Start by connecting the Inspector to your MCP server. For Corcava:

Connection Parameters

Endpoint URL: https://app.corcava.com/mcp
Transport: HTTP/SSE (remote server)
Authentication: Bearer token (API key)

Using the Inspector CLI

If using the command-line Inspector:

mcp-inspector \
  --url https://app.corcava.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

⚠️ Security Note

Never commit your API key to version control. Use environment variables or secure key storage. In examples, we use YOUR_API_KEY as a placeholder.

Step 2: List Available Tools

Once connected, the first thing to verify is that tools are available. The Inspector should show a list of tools provided by the server.

Expected Output for Corcava

You should see tools like:

list_tasks
get_task
create_task
update_task
delete_task
list_projects
get_project
list_boards
get_board
list_task_comments
add_task_comment
start_time_tracking
stop_time_tracking
get_tracking_status

If No Tools Appear

If the tool list is empty, check:

Is the API key valid and active?
Is the endpoint URL correct?
Are there network/firewall issues?
Is the server running and accessible?

See our troubleshooting guide for more help.

Step 3: Make a Simple Tool Call

Test the connection by making a simple read-only tool call. Start with list_tasks:

Example: list_tasks

Tool Call:

{
  "tool": "list_tasks",
  "arguments": {
    "limit": 5
  }
}

Expected Response:

{
  "tasks": [
    {
      "id": 123,
      "title": "Example Task",
      "status": "open",
      ...
    }
  ],
  "total": 10
}

Interpreting the Response

A successful response means:

✅ Connection is working
✅ Authentication is valid
✅ Server is processing requests
✅ Tool is functioning correctly

Step 4: Test Authentication

Verify authentication is working correctly:

Valid Key Test

With a valid API key, you should:

Successfully connect
See tools listed
Be able to make tool calls

Invalid Key Test

With an invalid/revoked key, you should see:

401 Unauthorized error
Connection refused
No tools listed

Read 401 troubleshooting guide →

Corcava Example Flow

Here's a complete validation flow using Corcava as the example:

Validation Checklist

Connect to Server

mcp-inspector --url https://app.corcava.com/mcp \
  --header "Authorization: Bearer YOUR_API_KEY"

List Tools
Verify you see Corcava tools (list_tasks, create_task, etc.)
Test list_tasks
```
{
  "tool": "list_tasks",
  "arguments": {
    "limit": 5
  }
}
```
Should return a list of tasks (or empty array if none exist)
Test get_task
```
{
  "tool": "get_task",
  "arguments": {
    "task_id": 123
  }
}
```
Should return task details (or error if task doesn't exist)

Test create_task (Optional - Write Operation)

{
  "tool": "create_task",
  "arguments": {
    "title": "Test Task from Inspector",
    "description": "Testing MCP connection",
    "project_id": YOUR_PROJECT_ID
  }
}

Should create a task and return the new task object

⚠️ This will create a real task - use with caution!

Interpreting Errors

The Inspector helps you understand what went wrong:

401 Unauthorized

Meaning: Authentication failed

Common Causes:

Invalid API key
Revoked API key
Missing Authorization header
Wrong Bearer format

Fix 401 errors →

403 Forbidden

Meaning: Authenticated but not authorized

Common Causes:

Key doesn't have access to requested resource
Workspace/team permission mismatch
Resource doesn't exist or is private

Fix 403 errors →

400 Bad Request

Meaning: Invalid request parameters

Common Causes:

Missing required parameters
Invalid parameter types
Invalid IDs (task_id, project_id, etc.)
Validation errors

Fix validation errors →

Connection Refused / Timeout

Meaning: Can't reach the server

Common Causes:

Network connectivity issues
Firewall blocking connection
Corporate proxy interference
Server is down

Fix connection issues →

Debugging Checklist

Quick Debugging Checklist

✅ Verify API key is active in Corcava Settings → Integrations
✅ Check endpoint URL is correct: https://app.corcava.com/mcp
✅ Confirm Authorization header format: Bearer YOUR_API_KEY (with space)
✅ Test endpoint is reachable (try in browser or curl)
✅ Verify JSON syntax is valid (no trailing commas, proper quotes)
✅ Check network/firewall isn't blocking the connection
✅ Review server logs for error messages
✅ Try a simple read-only tool call first (list_tasks)
✅ Verify tool parameters match the expected schema
✅ Check for rate limiting (429 errors)

Advanced Debugging

Viewing Request/Response Payloads

The Inspector shows you the exact request and response:

Request Payload

POST https://app.corcava.com/mcp
Headers:
  Authorization: Bearer sk_...
  Content-Type: application/json

Body:
{
  "tool": "list_tasks",
  "arguments": {
    "limit": 10,
    "project_id": 456
  }
}

Response Payload

Status: 200 OK

Body:
{
  "tasks": [...],
  "total": 25,
  "has_more": true
}

Testing Error Scenarios

Use the Inspector to test error handling:

Call a tool with invalid parameters
Try accessing a non-existent resource
Test with a revoked API key
Verify error messages are helpful

Troubleshooting Common Issues

Issue: "Tools list is empty"

Possible Causes:

Authentication is failing silently
Server isn't returning tools
Client caching issue

Solution: Check auth first, then verify server is responding. See tools list troubleshooting.

Issue: "Tool call fails with validation error"

Possible Causes:

Missing required parameters
Wrong parameter types
Invalid IDs

Solution: Check the tool schema, verify parameter types match. See tools reference for correct parameters.

Issue: "Connection times out"

Possible Causes:

Network connectivity problems
Firewall blocking HTTPS
Corporate proxy issues
Server is overloaded

Solution: Test endpoint accessibility, check network settings. See connection troubleshooting.

Using Inspector Results

Once the Inspector confirms your server is working:

Share results with team: Document working configuration
Debug client issues: Compare Inspector results with client behavior
Validate changes: Test after server updates or configuration changes
Onboard new users: Use Inspector to verify their setup

Need More Help?

Check our comprehensive troubleshooting guides

Troubleshooting Index →Debugging Checklist