#Connect your agent (MCP)

Operlance ships an MCP server named operlance. It exposes every tool from the reference over stdio and authenticates with your agent token. The token lives in an environment variable, the config file in your repo never contains it.

#Environment

export OPERLANCE_AGENT_TOKEN="agt_…"          # from the owner (AI → Agents)
export OPERLANCE_API_URL="https://api.operlance.app"   # origin, without /v1

#Claude Code

claude mcp add operlance -e OPERLANCE_AGENT_TOKEN="$OPERLANCE_AGENT_TOKEN" -e OPERLANCE_API_URL="$OPERLANCE_API_URL" -- operlance-mcp

Or in .mcp.json (project scope, commit it, the token comes from the environment):

{
  "mcpServers": {
    "operlance": {
      "command": "operlance-mcp",
      "env": { "OPERLANCE_AGENT_TOKEN": "${OPERLANCE_AGENT_TOKEN}", "OPERLANCE_API_URL": "${OPERLANCE_API_URL}" }
    }
  }
}

#Claude Desktop

claude_desktop_config.json → mcpServers:

{
  "mcpServers": {
    "operlance": {
      "command": "operlance-mcp",
      "env": { "OPERLANCE_AGENT_TOKEN": "agt_…", "OPERLANCE_API_URL": "https://api.operlance.app" }
    }
  }
}

Claude Desktop cannot read shell variables, so the token has to be pasted into this file. Keep the file out of any repository and rotate the token from the panel if it leaks (AI → Agents → Rotate token).

#Cursor and other clients

Any MCP client that supports stdio servers works the same way: command operlance-mcp, env OPERLANCE_AGENT_TOKEN and OPERLANCE_API_URL. In Cursor: Settings → MCP → Add server with the JSON above.

#Remote (HTTP transport)

No install: the same tools over HTTP, authenticated with a Bearer header. Never put the token in a config file that gets committed, keep it in an environment variable and reference it as shown.

Claude Code:

claude mcp add --transport http operlance https://mcp.operlance.app/mcp --header "Authorization: Bearer $OPERLANCE_TOKEN"

Claude Desktop, Cursor and other HTTP-capable clients:

{
  "mcpServers": {
    "operlance": {
      "url": "https://mcp.operlance.app/mcp",
      "headers": { "Authorization": "Bearer ${OPERLANCE_TOKEN}" }
    }
  }
}

Claude Desktop cannot read shell variables in headers, so paste the token directly there instead and keep that file out of any repository.

#First call

Ask the agent to run get_onboarding. It returns what Operlance is, which businesses the agent can see, its grants and limits, the available tools and a few worked examples, about 2 000 tokens, no secrets. The same text is available as the MCP resource operlance://onboarding.

#What the server does

• One tool = one (sometimes two) REST calls. No business logic lives in the server.
• Every result carries coverage, fx (when currencies were converted) and request_id.
• Writes take idempotency_key and reason; results are executed or pending_approval.
• Errors are the same codes as the REST API.