Skip to content

HTTP APIs#

Most enterprise systems are HTTP APIs, not MCP servers. Lens Agents reaches them two ways: turn an OpenAPI document into tools, or allow the domain outright and let the agent make ordinary requests.

Which approach#

OpenAPI connector Domain allow rule
The agent sees Named tools with typed parameters A reachable hostname
Control granularity Per operation Per method and URL path
Needs An OpenAPI 3.x document Nothing
Best for APIs agents should call deliberately Package registries, docs sites, APIs an SDK already wraps

Both go through the same policy-controlled proxy and produce the same audit events.

From an OpenAPI document#

Auto-discover#

Point the platform at a base URL and let it find the document:

curl -fsS -X POST \
  -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  -H "Content-Type: application/json" \
  "https://agents.example.com/v1/mcp-servers/$CONNECTOR_ID/discover/url" \
  -d '{"url": "https://api.internal.example.com"}'

The response reports the URL that produced a usable document and every URL it tried, with the outcome of each — so a failed discovery tells you what to fix rather than failing without explanation.

Import directly#

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/http \
  -d '{
    "name": "billing",
    "displayName": "Billing API",
    "url": "https://api.internal.example.com",
    "openapi": '"$(cat openapi.json)"'
  }'

An agent connected to the MCP endpoint can do the same in one instruction, because it can fetch the document itself:

Register the API at https://api.internal.example.com as an HTTP
connector called billing ("Billing API") in the production project.
Fetch its OpenAPI document first, then tell me which operations it
turned into tools.

Each operation becomes a namespaced tool — billing__listInvoices — with parameters typed from the schema.

Set clusterId to reach an API that only exists inside a registered cluster; the transport mode switches to tunnel automatically.

Preview before committing#

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/discover/preview \
  -d '{"url": "https://api.internal.example.com"}'

Probes and reports what would be created, without creating anything.

Spec changes go through review#

An upstream API that changes should not silently change what your agents can do. Imported and re-discovered documents land in a pending lane instead of taking effect.

# What is waiting
curl -fsS -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/mcp-servers/$CONNECTOR_ID/specs/pending

# What would change
curl -fsS -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/mcp-servers/$CONNECTOR_ID/specs/$SPEC_ID/diff

# Accept it
curl -fsS -X POST -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/mcp-servers/$CONNECTOR_ID/specs/$SPEC_ID/promote

# Or discard it
curl -fsS -X DELETE -H "Authorization: Bearer $LENS_AGENTS_TOKEN" \
  https://agents.example.com/v1/mcp-servers/$CONNECTOR_ID/specs/$SPEC_ID

Each pending spec records where it came from: admin, synced, discovered, or imported.

New operations still need a policy to name them in allowedTools before an agent can call them. Promoting a spec adds to the catalog, never to an agent's reach.

Allowing a domain outright#

For everything that does not warrant a connector, a policy domain rule is enough:

name: docs-and-packages
networkDefaultVerdict: deny
allowedDomains:
  - pattern: registry.npmjs.org
    verdict: allow
    transport: direct
  - pattern: "*.internal.example.com"
    verdict: allow
    transport: upstream
    scheme: https
    rules:
      - method: GET
        path: /v1/reports/*
Field Meaning
pattern Hostname or wildcard.
verdict allow or deny. First match wins.
transport upstream routes through the platform, enabling credential injection and full audit. direct allows the call without interception.
scheme Restrict to http or https. Omit to match both.
rules Method and path restrictions.

Use transport: upstream for anything that needs a credential attached or a detailed audit record. direct is for high-volume, low-risk traffic such as package downloads.

Pair the domain rule with a credential to make the agent authenticated.