MCP

Worksi speaks the Model Context Protocol (MCP) in two ways. Both live on your gateway, https://gateway.worksi.ai, and use the Streamable HTTP transport (JSON‑RPC 2.0).

Worksi MCP server#

The credential you connect with decides which tools you see.

Agent tools (API key)#

For agents that report their own work. The spans go through the normal ingest path, so these runs appear in traces, feed the detectors and follow your capture mode.

Operator tools (personal access token)#

For people working from an AI assistant. The permissions of your role apply, and changes are written to the audit log.

Both credential types can read two resources: worksi://docs/quickstart and worksi://status. Requests are rate limited per credential.

Connect a client#

Use an API key for the agent tools or a personal access token for the operator tools.

{  "mcpServers": {    "worksi": {      "command": "npx",      "args": [        "-y",        "mcp-remote",        "https://gateway.worksi.ai/mcp",        "--header",        "Authorization:${WORKSI_AUTH}"      ],      "env": {        "WORKSI_AUTH": "Bearer aiw_…"      }    }  }}

{  "mcpServers": {    "worksi": {      "url": "https://gateway.worksi.ai/mcp",      "headers": {        "Authorization": "Bearer aiw_…"      }    }  }}

{  "inputs": [    {      "type": "promptString",      "id": "aiw",      "description": "Bearer aiw_…",      "password": true    }  ],  "servers": {    "worksi": {      "type": "http",      "url": "https://gateway.worksi.ai/mcp",      "headers": {        "Authorization": "${input:aiw}"      }    }  }}

Transport:  Streamable HTTP, JSON-RPC 2.0URL:        https://gateway.worksi.ai/mcpHeader:     Authorization: Bearer aiw_…Credential: an aiw_sk_… API key, or            an aiw_pat_… access token

• Claude Desktop starts local servers from claude_desktop_config.json, so this configuration bridges the remote endpoint with the open-source mcp-remote package (it needs Node.js).
• Cursor reads ~/.cursor/mcp.json for all projects or .cursor/mcp.json for one project.
• VS Code reads .vscode/mcp.json in your workspace and asks for the key once.

To check the endpoint from a terminal:

curl -s https://gateway.worksi.ai/mcp \  -H "Authorization: Bearer $AIW_API_KEY" \  -H "Content-Type: application/json" \  -H "Accept: application/json, text/event-stream" \  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize",       "params": {"protocolVersion": "2025-06-18",                  "capabilities": {},                  "clientInfo": {"name": "curl",                                 "version": "1.0"}}}'

MCP gateway: govern any MCP server#

Register an upstream MCP server in Workforce → MCP servers, or with POST /api/v1/mcp-servers: its Streamable HTTP URL, an optional auth header (the secret is encrypted and never shown again) and an optional list of allowed tools. Each server gets a slug and its own endpoint:

https://gateway.worksi.ai/mcp/servers/{slug}

Point the agent’s MCP client at that endpoint with an API key, and send the agent’s name in X-AIW-Agent so agent-level tool rules apply:

{  "mcpServers": {    "github-via-worksi": {      "url": "https://gateway.worksi.ai/mcp/servers/github",      "headers": {        "Authorization": "Bearer aiw_sk_live_…",        "X-AIW-Agent": "release-agent"      }    }  }}

Worksi proxies the session and governs it:

• tools/list only returns the tools that the server’s allowed list, your tool_allowlist policies and the agent’s allowed tools permit. Tools are identified as {slug}.{tool}.
• tools/call is checked against your tool policies first. A disallowed tool (enforce mode) returns JSON‑RPC error -32001 tool_not_allowed. A tool that needs approval returns -32002 approval_required with the approval_id of a pending approval that Worksi creates for you. Once a person approves it, retry the call with the X-AIW-Approval-Id header or _meta.approval_id.
• Every tool call is recorded as a tool_call span (tool, server, argument hash, a result preview according to your capture mode, status and latency), and the tool appears in your AI inventory.
• initialize, ping, resources/*, prompts/* and notifications pass through. Upstream errors are returned as they are, and an upstream timeout returns -32003.

Refresh re-reads a server’s tool catalog. Upstream URLs are checked against private-network and cloud-metadata addresses before every connection.