Connection guide

Start with a client identity

When agent access is enabled, sign in and open Agents. Create a client identity for the intended workspace, choose only the scopes it needs, and set its expiry. Keep the resulting credential in your client’s secure configuration or environment, never in source control or a browser page.

A client credential identifies an agent. It does not grant access to every account, private record or service that its human owner can use.

Connect to the MCP endpoint

Configure an HTTP MCP connection to https://www.specifywork.com/api/mcp. Supply the client credential as a Bearer authorization header. Your client must support this endpoint’s HTTP transport and protocol version.

Initialize the connection, then use tools/list to discover the tool definitions. Each request rechecks the credential; reconnecting does not restore revoked access.

{
  "jsonrpc": "2.0",
  "id": "example_initialize",
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": {
      "name": "example-client",
      "version": "1.0.0"
    }
  }
}

Verify before writing

Call verify_access and inspect the effective scopes. Start with get_context or another authorized read. When the task requires writing, use the exact tool input schema and keep the same idempotency key for a retry of that same request.

{
  "jsonrpc": "2.0",
  "id": "example_verify",
  "method": "tools/call",
  "params": {
    "name": "verify_access",
    "arguments": {}
  }
}

Record session activity

Create an agent session, keep it current with heartbeats, attach useful evidence to linked work, and complete or cancel the session when the task ends. An approval decision authorizes only its defined action; it is not proof that the action executed.