Skip to main content
Simforge provides an MCP (Model Context Protocol) server that lets coding agents like Cursor, Claude Code, Codex, and Windsurf set up Simforge tracing in your codebase automatically. The MCP server provides two tools:
  • setup_simforge — Returns a language-specific SDK setup guide with correct API usage, code examples, and best practices
  • get_simforge_api_key — Retrieves your API key for the agent to configure

​
API Key Requirements

The MCP server requires authentication to access your organization’s API keys and provide personalized setup guidance. You have two options:
  1. Automatic Authentication (Recommended): Use the setup page which automatically configures authentication
  2. Manual Configuration: Add authentication headers to your MCP client configuration

​
Supported Languages

TypeScript

@goharvest/simforge — withSpan wrapper

Python

simforge-py — @span decorator

Ruby

simforge — simforge_span macro

Go

simforge-go — Start/End spans
The easiest way to connect your agent is through the Simforge setup page:
  1. Get your API key: Your API key is automatically created and displayed on the setup page
  2. Choose your agent: The page shows pre-configured setup instructions for Cursor, Claude Code, and other MCP clients
  3. Copy and paste: Each configuration includes your API key automatically - no manual copying needed
The setup page provides:
  • One-click installation links for supported clients
  • Ready-to-use configuration files with your API key embedded
  • Command-line instructions for terminal-based setup

​
Manual Configuration

If you prefer to set up the MCP connection manually, you’ll need to include your API key in the configuration.

​
Getting Your API Key

  1. From the setup page: Visit simforge.goharvest.ai/setup and copy your API key
  2. From the dashboard: Click your profile avatar → API Keys → Create/view your key
See the API Keys guide for detailed key management instructions.

​
Cursor

Add this to your .cursor/mcp.json (project-level) or ~/.cursor/mcp.json (global): 
{
  "mcpServers": {
    "simforge": {
      "type": "streamable-http",
      "url": "https://simforge.goharvest.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}
Replace YOUR_API_KEY with your actual API key, or use the pre-configured setup from the setup page.

​
Claude Code

Run this in your terminal (replace YOUR_API_KEY with your actual key): 
claude mcp add --scope user --transport http Simforge https://simforge.goharvest.ai/mcp --header "Authorization:Bearer YOUR_API_KEY"

​
Codex

Set your API key as an environment variable: 
export SIMFORGE_API_KEY="YOUR_API_KEY"
Then add this to ~/.codex/config.toml (global) or .codex/config.toml (project-level): 
[mcp_servers.simforge]
url = "https://simforge.goharvest.ai/mcp"
bearer_token_env_var = "SIMFORGE_API_KEY"

​
Windsurf

Add this to your MCP configuration: 
{
  "mcpServers": {
    "simforge": {
      "serverUrl": "https://simforge.goharvest.ai/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

​
How It Works

Once connected, your coding agent can:
  1. Call get_simforge_api_key to retrieve your API key (requires your Simforge session)
  2. Call setup_simforge with a language parameter (typescript, python, ruby, or go) to get a complete setup guide
  3. Follow the guide to install the SDK, initialize the client, and instrument your functions
The agent receives the full SDK API reference including code examples, so it can make the correct changes without browsing documentation or guessing APIs.

​
Example Workflow

Ask your coding agent: 
Set up Simforge tracing for my project
The agent will:
  1. Detect your project language
  2. Call the MCP tools to get the API key and setup guide
  3. Install the SDK
  4. Read your codebase and identify all AI workflows
  5. Present you with a list of workflows it found, and why each is worth instrumenting
  6. Instrument whichever workflows you choose — one, several, or all
The agent presents options and lets you choose which workflows to instrument, so you stay in control. Each option explains what visibility tracing gives you into that workflow.

​
Troubleshooting

​
Authentication Issues

If your agent can’t access the MCP tools:
  1. Check your API key: Ensure you’re using the correct API key from your dashboard
  2. Verify the header format: Use Authorization: Bearer YOUR_API_KEY (note the space after “Bearer”)
  3. Organization access: Make sure you’re logged into the correct organization in Simforge
  4. Try the setup page: Use the automatic configuration to avoid manual errors

​
Connection Problems

Common issues and solutions:
  • MCP server not found: Verify the URL is https://simforge.goharvest.ai/mcp
  • Tools not available: Restart your coding agent after adding the MCP configuration
  • API key errors: Generate a new API key from the API Keys page
  • Network issues: Ensure your network allows HTTPS connections to simforge.goharvest.ai

​
Getting Help

If you’re still having trouble:
  1. Check the API Keys documentation for key management
  2. Visit the setup page for automatic configuration
  3. Contact support if the issue persists