Skip to main content

​
Overview

MCP (Model Context Protocol) enables you to extend Sphinx’s capabilities by connecting external tools, services, and data sources. Sphinx utilizes MCP a little bit differently than most agents: When Sphinx invokes an MCP tool, Sphinx will decide if the output of the MCP tool is best held in context, or if it is actually data. If the MCP call is considered data, Sphinx will instead keep it inside the Python kernel. An example of this could be the MLB MCP server, which dumps many lines of data into context.

​
Connecting to an MCP Server

Sphinx follows the MCP standard for defining MCP connections. To modify your MCP config, click the gear icon in the VS Code Extension. An example is as follows: 
{
  "mcpServers": {
    "deepwiki": {
      "description": "MCP tool to get information about public git repos",
      "url": "https://mcp.deepwiki.com/mcp"
    },
    "linear": {
      "description": "Linear MCP server for project management",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.linear.app/sse"]
    }
  }
}

​
Debugging

When an MCP server isn’t working as expected, here are some steps to troubleshoot:

​
Check Connection Status

Verify that your MCP server is properly connected in the Sphinx interface. Look for connection indicators or error messages in the configuration panel.

​
Review Server Logs

For command-based MCP servers (using command and args), check the output logs. Connection failures, authentication errors, or tool invocation issues will typically appear here.

​
Test Individual Tools

Try invoking MCP tools one at a time to isolate which specific tool or operation is failing. This helps narrow down whether the issue is with the server connection or a specific tool implementation.

​
Common Issues

  • Verify the URL or command is correct
  • Check network connectivity and firewall settings
  • Ensure any required environment variables or credentials are set
  • For remote servers, confirm the endpoint is accessible
  • Review the tool’s input parameters and ensure they match the expected schema
  • Check if the MCP server has proper permissions for the requested operation
  • Look for rate limiting or quota issues with the underlying service
  • Verify that the MCP server is returning data in the expected format
  • Check if authentication or authorization is working correctly
  • Review the description field to ensure Sphinx is selecting the right tool for the task
When debugging, start with simpler MCP tools or operations to verify basic connectivity before moving to more complex use cases.