MCP

What the MCP server does

The MCP server lets Codex, Claude Code, and other MCP-capable clients create and manage TraceOps work items without talking to HTTP directly. Your MCP client starts the server locally, and that server talks to the hosted TraceOps.Dev API. For onboarding, see setup.

• Server name: traceops-dev.
• Transport: stdio.
• Hosted API target: `https://api.traceops.dev/api`.

Required configuration

The MCP server only needs the hosted API URL, your key, and optionally a default tenant context.

[mcp_servers.traceops-dev]
command = "node"
args = ["/absolute/path/to/TraceOps.Dev/mcp-server/dist/src/server.js"]
tool_approval = "auto"

[mcp_servers.traceops-dev.env]
TRACEOPS_API_BASE_URL = "https://api.traceops.dev/api"
TRACEOPS_API_KEY = "<your-traceops-api-key>"
TRACEOPS_DEFAULT_TENANT_ID = "<your-tenant-id>"

• The API is hosted by TraceOps.Dev; you do not need to deploy backend infrastructure.
• You only need your key or token and the tenant context you want the client to use.
• You do not need Azure Function URLs, GitHub secrets, or internal storage knowledge.
• `TRACEOPS_DEFAULT_TENANT_ID` is optional. Keep it only if you want a default tenant.

Available tools

The current implementation exposes exactly eight tools and returns concise JSON results.

• get_context
• create_workitem
• search_workitems
• get_workitem
• get_next_workitem
• update_workitem_status
• claim_workitem
• update_workitem_links

Tenant and repository context

Tenant context can come from the tool call or from `TRACEOPS_DEFAULT_TENANT_ID`. The MCP server does not define a default `repoId`, so repository context must still be supplied for work item tools.

• Explicit `tenantId` in a tool call overrides `TRACEOPS_DEFAULT_TENANT_ID`.
• Work item tools always require `repoId`.
• The server mirrors the hosted API boundary of one tenant and repository partition per operation.

Claude Code example

Claude Code uses the same hosted API URL and the same secret placeholders.

{
  "mcpServers": {
    "traceops-dev": {
      "command": "node",
      "args": ["/absolute/path/to/TraceOps.Dev/mcp-server/dist/src/server.js"],
      "env": {
        "TRACEOPS_API_BASE_URL": "https://api.traceops.dev/api",
        "TRACEOPS_API_KEY": "<your-traceops-api-key>",
        "TRACEOPS_DEFAULT_TENANT_ID": "<your-tenant-id>"
      }
    }
  }
}

• Use placeholders in documentation and keep real secrets in local secure config.
• The MCP client runs locally; the TraceOps.Dev API stays hosted.

Troubleshooting

Most MCP problems map directly to API auth, tenant membership, or missing context.

• `tenantId` is required when `TRACEOPS_DEFAULT_TENANT_ID` is not configured: set the env var or pass `tenantId` explicitly.
• `401 Unauthorized` usually means the key is wrong, expired, revoked, or pointed at the wrong API base URL.
• `403` means the key lacks the required scope or the user is not a member of that tenant.
• `409` on `claim_workitem` means another active claim exists.
• The MCP server only covers workflow state. It does not create branches, edit files, commit, push, or open pull requests.