MCP connectors#

A connector is an upstream service the platform can reach on an agent's behalf. Register the MCP server your team already runs — Slack, Jira, an internal service — and its tools become available to agents, one allowlisted tool at a time.

Agents never talk to the upstream directly. That indirection is what makes tool-level control and credential isolation possible.

Register a connector#

APIAgentCLI

curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/projects/$PROJECT_ID/mcp-servers \
  -d '{
    "name": "jira",
    "displayName": "Jira",
    "url": "https://mcp.internal.example.com/jira",
    "transport": "streamable-http"
  }'

Register an MCP connector called jira in the production project,
pointing at https://mcp.internal.example.com/jira over
streamable-http, then tell me which tools it discovered.

nexusctl connector create --project production \
  --name jira \
  --display-name "Jira" \
  --url https://mcp.internal.example.com/jira \
  --transport streamable-http

Flag	Notes
`--name`	Lowercase slug, unique in the project. Becomes the tool namespace and the CLI name inside sandboxes.
`--transport`	`streamable-http` (default) or `sse`.
`--cluster`	Route through a cluster tunnel instead of dialling directly.
`--defer-discovery`	Skip the initial probe. Use when the upstream needs a credential attached first.

On creation the platform probes the upstream and records its tool list.

Discovery and sync#

APIAgentCLI

curl -fsS -X POST -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/mcp-servers/$CONNECTOR_ID/sync

curl -fsS -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/mcp-servers/$CONNECTOR_ID

Sync the jira connector in production and tell me which tools are
new since the last sync.

nexusctl connector sync jira --project production
nexusctl connector describe jira --project production

sync re-probes the upstream and refreshes the tool list. describe shows the connector's identity, status, transport, discovered tools, and attached credentials in one view.

New tools appearing upstream do not become available automatically — a policy has to name them. An upstream that grows a delete_everything tool grows it in your catalog, not in your agents' hands.

Control which discovered tools are even listed:

APIAgent

ENTRY=jira__delete_issue

curl -fsS -X PATCH \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://agents.example.com/v1/mcp-servers/$CONNECTOR_ID/entries/$ENTRY/visibility" \
  -d '{"visible": false}'

Hide the jira__delete_issue tool on the jira connector so it is
not listed at all.

Tool names are namespaced by the connector slug — jira__create_issue — so two connectors offering search do not collide.

Credentials#

Upstreams that need authentication get a connector credential. Three kinds:

`authType`	How it works	Use for
`static`	A bearer token you supply, encrypted at rest.	Internal services with a long-lived token.
`oauth-client-credentials`	The platform exchanges a client id and secret for a bearer at create time, and refreshes on expiry.	Machine-to-machine OAuth.
`oauth-authorization-code`	Each actor authorizes through their own consent flow; tokens are stored per actor.	Services where actions must be attributable to a person.

curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  https://agents.example.com/v1/projects/$PROJECT_ID/mcp-servers/$CONNECTOR_ID/credentials \
  -d '{
    "name": "jira-bot",
    "authType": "oauth-client-credentials",
    "tokenUrl": "https://auth.example.com/oauth/token",
    "clientId": "...",
    "clientSecret": "...",
    "scope": "read:issues write:issues"
  }'

An agent can do the same — "add an OAuth client-credentials credential called jira-bot to the jira connector" — but the client secret then lives in its conversation history. Use the API for production secrets.

For oauth-authorization-code, tokenUrl and clientId are optional — the platform discovers the endpoints, and falls back to dynamic client registration when no client id is given.

Per-actor tokens and delegation#

With oauth-authorization-code, each actor authorizes once and their own token is used for their calls, so the upstream's audit log names the right person.

When a caller has no grant of their own, the platform falls back to the most recently authorized grant on the credential. One administrator authorizing once is therefore enough to delegate access to every actor a policy binds — convenient, and worth knowing before you rely on per-actor attribution upstream.

Granting tools to agents#

Registering a connector makes it available. A policy grants it, and must name the tools:

name: jira-readonly
connectors:
  - connectorId: 123e4567-e89b-12d3-a456-426614174000
    allowedTools:
      - jira__search_issues
      - jira__get_issue
    credentialId: 223e4567-e89b-12d3-a456-426614174000

allowedTools is required and has no wildcard. An empty array denies every tool in that reference. Administrators choose tools explicitly — there is no "grant everything" shortcut, deliberately.

Reaching services behind a firewall#

An MCP server that only exists inside a registered cluster is reachable over the same reverse tunnel:

AgentCLI

Register http://mcp-tools.internal.svc.cluster.local:8080 as a
connector called internal-tools in production, reached through the
prod-eu cluster.

nexusctl connector create --project production \
  --name internal-tools \
  --display-name "Internal Tools" \
  --url http://mcp-tools.internal.svc.cluster.local:8080 \
  --cluster prod-eu

Setting --cluster switches the connector's transport mode to tunnel. No public endpoint and no inbound firewall rule.

What agents see#

An agent connected to the MCP endpoint sees the allowlisted tools of every connector its policies grant, alongside the platform's own tools. Inside a sandbox, each connector also appears as a CLI.

Tools a policy does not grant are not listed at all, so an agent cannot discover its way to them.

HTTP APIs — turning an OpenAPI document into governed tools
MCP endpoint — how agents consume these tools
Policies — granting connectors and tools
Audit trail — every tool call, allowed and denied