◉doc.ts
traceops.dev

Start

Setup

Sign in to the hosted service, create a key, configure MCP clients, and verify the connection.

Before you start

TraceOps.Dev is a hosted workflow system for repository work items. You sign in to the hosted product, work inside your tenant context, and connect local tools to the hosted API. The hosted website is the user-facing entry point, while the core TraceOps.Dev API remains the system of record for product data and authorization. For API details, see API docs. For MCP behavior, see MCP docs.

  • Open the hosted sign-in page: https://traceops.dev/login.
  • The hosted solution already runs the TraceOps.Dev API for you at https://api.traceops.dev.
  • You do not need to deploy Azure resources, manage GitHub secrets, or know internal storage details to use the product.
  • If you only use your personal tenant, the first hosted login creates it automatically.
  • If you need access to a shared tenant, an existing tenant admin or owner must add your membership before you can work in that tenant.
  • Keep your API key or token in local secret storage and never commit it to git.

Sign in

Start at https://traceops.dev/login. After you sign in, the hosted app connects your account to TraceOps.Dev and takes you to the normal authenticated work item view at `/app/workitems`.

  • Sign in with the provider offered on https://traceops.dev/login.
  • After login, open the workitems app to browse tenant-scoped work.
  • Use the app settings area to create and revoke your own API keys if that feature is enabled for your account.

Get your key and tenant context

For user-driven API and MCP access, use your TraceOps.Dev key or token and the tenant context you want to work in. The hosted API handles storage and authorization for you.

  • If the app provides personal API keys, create one in the hosted app and copy the raw value when it is shown.
  • Use that key in `Authorization: Bearer <key>` when you call the hosted API directly.
  • Keep track of the tenant you want the client to use. If your MCP client supports a default tenant setting, configure it there.
  • Revoked, expired, or wrong keys return `401 Unauthorized`.

Configure Codex

The MCP client runs a local MCP server process, and that server talks to the hosted TraceOps.Dev API. You only need your local MCP server path, your key, and your tenant context. See MCP docs for the workflow model.

# ~/.codex/config.toml
[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>"

[mcp_servers.traceops-dev.tools.search_workitems]
approval_mode = "approve"

[mcp_servers.traceops-dev.tools.create_workitem]
approval_mode = "approve"

[mcp_servers.traceops-dev.tools.claim_workitem]
approval_mode = "approve"

[mcp_servers.traceops-dev.tools.update_workitem_status]
approval_mode = "approve"

[mcp_servers.traceops-dev.tools.get_workitem]
approval_mode = "approve"

[mcp_servers.traceops-dev.tools.get_context]
approval_mode = "approve"
  • The hosted API is already running at `https://api.traceops.dev/api`.
  • You do not need Azure Function URLs, GitHub secrets, or an Azure deployment for this setup.
  • If your MCP workflow uses a default tenant, keep `TRACEOPS_DEFAULT_TENANT_ID`; otherwise remove it and pass `tenantId` in tool calls.
  • `repoId` is still required on work item tools even when a default tenant is configured.

Configure Claude Code

Use the same hosted API URL in Claude Code. The local MCP server still runs on your machine, but the backend is the hosted TraceOps.Dev API. See MCP docs if you need the connection model.

{
  "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, not real secrets, in shared documentation.
  • Store the real key in the client's secure local config location.

Test the connection

A quick verification path is to confirm context, search for work, and create one small test item. You can validate through MCP or through the hosted API described in API docs.

get_context

search_workitems
{ "repoId": "AndersMaletzki/TraceOps.Dev", "limit": 5 }

create_workitem
{
  "repoId": "AndersMaletzki/TraceOps.Dev",
  "workItemType": "Issue",
  "category": "Documentation",
  "title": "Example test item",
  "description": "Verify that the MCP server can create a work item.",
  "severity": "Low",
  "source": "manual",
  "createdBy": "your-name"
}
  • If `TRACEOPS_DEFAULT_TENANT_ID` is not configured, pass `tenantId` explicitly on each tool call.
  • Use `claim_workitem`, `update_workitem_status`, and `update_workitem_links` as work progresses.
  • Open the hosted login page again at https://traceops.dev/login if you need to confirm your account can still access the right tenant.

Troubleshooting

Most setup failures come from missing tenant context, invalid keys, or tenant membership mismatches.

  • `tenantId` is required when `TRACEOPS_DEFAULT_TENANT_ID` is not configured: add the env var or pass `tenantId` in the tool call.
  • `401 Unauthorized`: the key is wrong, expired, revoked, or pointed at the wrong base URL.
  • `403` tenant or scope errors: your key belongs to another tenant, your membership is missing, or the key lacks the required work item scope.
  • `409` on `claim_workitem`: another active claim exists.
  • `404` from `get_next_workitem`: there are no matching actionable items in that tenant and repository filter.