Cursor

Connect Cursor to Semaphor so you can query analytics data directly from your IDE.

1. Generate a Project Token

The quickest way to get a token for testing:

1. Go to the Projects page in Semaphor
2. Click the Embed button on your project row
3. Navigate to the Generate Token tab
4. Click Show on "Generate a sample project token"
5. Set the expiry duration and click Generate Token
6. Click Copy Token

For production use, generate tokens programmatically from your backend using the Token API:

curl -X POST https://semaphor.cloud/api/v1/token \
  -H "Content-Type: application/json" \
  -d '{
    "type": "project",
    "projectId": "p_1234567890abcdef",
    "projectSecret": "ps_abcdef1234567890",
    "orgUserId": "your_user_id"
  }'

2. Configure Cursor

Add to your ~/.cursor/mcp.json:

{
  "mcpServers": {
    "semaphor": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "https://semaphor.cloud/api/mcp",
        "--transport", "http-only",
        "--header", "Authorization:${SEMAPHOR_AUTH_HEADER}"
      ],
      "env": {
        "SEMAPHOR_AUTH_HEADER": "Bearer YOUR_PROJECT_TOKEN"
      }
    }
  }
}

Replace YOUR_PROJECT_TOKEN with the accessToken from Step 1.

3. Restart Cursor

Restart Cursor to pick up the new configuration.

4. Test the Connection

In Cursor's AI chat, type:

Call semaphor_get_analysis_context

You should see your project's data context returned.

First Steps After Connecting

Start with semaphor_get_analysis_context — your project is already scoped by the token.

Troubleshooting

• "Tool not found" — Restart Cursor after changing mcp.json
• Connection errors — Verify the URL and token. Ensure mcp-remote is available: npx mcp-remote --version
• "No active project" — In dev mode, pass projectId explicitly on project-scoped tool calls. Use semaphor_list_projects to find your project ID

See Troubleshooting for more common issues.