Skip to content

MCP endpoint#

Lens Agents speaks Model Context Protocol (MCP). Any MCP client — Claude Code, Claude Desktop, Cursor, an agent you wrote yourself — connects to the platform and gets three families of tools at once:

  • Platform tools for administering Lens Agents itself: projects, policies, sandboxes, credentials, audit, spending. See Platform tools.
  • Agent tools for working inside a sandbox: run commands, read and edit files, spawn processes. See Agent tools.
  • Connector tools aggregated from every MCP connector and HTTP API the caller's policies grant.

This is one of three ways to drive the platform, alongside the REST API and nexusctl. All three enforce the same identity, RBAC, policies, and audit.

Once a client is connected, the Agent tab that appears on pages throughout these docs shows the plain-English equivalent of each command — "cap the nightly-refactor sandbox at $50 a month" instead of a flag list. The tools an agent can actually use depend on how it signed in; see what each identity sees.

Endpoints#

Endpoint Scope
https://agents.example.com/mcp Organization-wide. First-party platform tools, plus connectors aggregated across every project you can reach.
https://agents.example.com/projects/{projectId}/mcp A single project. Use it to pin an agent to one project's tools and nothing else.

Both use streamable HTTP.

Connect a client#

claude mcp add --transport http lens-agents https://agents.example.com/mcp

The first tool call triggers a browser sign-in. No token to create or store.

Add the endpoint as a connector in Settings → Connectors, using the URL https://agents.example.com/mcp, and complete the sign-in prompt.

For CI, scripts, and agents that cannot open a browser, authenticate with an API token as a bearer token:

curl -fsS -X POST https://agents.example.com/mcp \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

An interactive sign-in gives you the full surface your role allows. A token gives you the surface that token's role allows — which is deliberately smaller.

Tools are filtered by who is calling#

The endpoint does not expose one fixed tool list. It builds the list per caller.

Identity Sees
User (interactive sign-in) The full platform surface, including destructive administration: create and delete orgs, manage connectors, set spending limits.
API token Day-to-day operations — sandboxes, policies, credentials, clusters, audit queries — but not org lifecycle or connector management.
Sandbox Only what a running agent needs, such as its own spend and usage. A sandbox cannot administer the platform that runs it.

On top of that, connector tools appear only where a policy grants the caller that connector, and only the tools that policy whitelists.

The practical effect: an agent handed a token cannot escalate by discovering administrative tools, because the tools are never listed for it.

Discovering what you have#

nexusctl connector list --project production

Or call tools/list from your client. The result is authoritative for your identity, your policies, and the platform version you are running — which is why these docs list tool domains rather than reproducing every parameter.

The OpenAPI document for the REST equivalents is served at /v1/openapi.json.

Two directions, one protocol#

MCP shows up on both sides of the platform, which is worth keeping straight:

graph LR
    client[MCP clients<br><i>Claude Code · Cursor · your agent</i>] -->|MCP| platform[Lens Agents]
    platform -->|MCP| upstream[MCP connectors<br><i>registered upstream servers</i>]
    platform -->|HTTP| apis[HTTP APIs<br><i>exposed as tools</i>]

Inbound, clients connect to the platform's endpoint and get governed tools. Outbound, the platform connects to MCP connectors you register and re-exposes their tools under policy. A client never talks to an upstream server directly, which is what makes tool-level allowlisting and credential isolation possible.

Everything is audited#

Every tools/call is written to the audit trail: who called, which tool, which project, the result, and how long it took. Calls that a policy denied are recorded too, which makes "why can my agent not do X" a query rather than a guess.