How connectors work

Connectors let Aperture reach out to external services on behalf of your agents. A connector defines an upstream endpoint and an optional authentication method. Agents interact with a single proxy endpoint, and Aperture handles credential injection, protocol detection, and access control behind it. This page explains the model so you can predict how a connector behaves before you configure one. For exact fields and values, refer to the connectors reference.

Connectors and providers

Aperture has two kinds of outbound integration, and they divide cleanly by what they carry:

• Providers route LLM requests to upstream model APIs.
• Connectors route tool calls and API requests to upstream services.

Together they give Aperture full visibility into both model usage and tool usage through one gateway. A connector never serves model completions. A provider never exposes tools. When you want an agent to call a tool or query an API, you reach for a connector.

Two protocols

Each connector declares a protocol that determines how Aperture talks to the upstream and how agents reach it.

• MCP connectors: Point at remote Model Context Protocol servers. Aperture aggregates their tools and resources behind the /v1/mcp endpoint. An agent discovers and calls tools through Aperture without knowing which backend serves each tool.
• HTTP connectors: Turn Aperture into an authenticated reverse proxy. An agent sends a request to /v1/connectors/<id>/<path>, and Aperture forwards it to the upstream API with credentials injected automatically.

You can mix both protocols in one configuration. MCP tools surface through /v1/mcp, and HTTP APIs surface through their proxy paths. When at least one HTTP connector exists, Aperture also exposes a built-in tool that lets models discover the available HTTP connectors.

Name prefixing

Each connector ID becomes a name prefix, which prevents collisions when two servers expose a tool with the same name. Tools take the ID and an underscore (local_search). Resources and resource templates take the ID and a hyphen (local-files://readme.md). Aperture strips the prefix when it forwards a call to the upstream. This is why connector IDs allow only letters and digits: underscores and hyphens are reserved as separators in the prefixed names exposed to agents.

The authentication model

Connectors centralize credentials. Instead of distributing API keys and tokens to every agent runtime, you store them once in the Aperture configuration, and Aperture injects the right credential on each outbound request. Rotating a credential happens in one place.

Aperture supports several authentication schemes, including static tokens, API keys, HTTP basic, and two OAuth 2.0 flows. The distinction that shapes behavior most is shared versus per-user credentials:

• Shared credentials such as static tokens, API keys, basic, and OAuth 2.0 client credentials authenticate Aperture itself to the upstream. Every user with a matching grant uses the same credential. Scope these narrowly, ideally read-only.
• Per-user credentials such as an OAuth 2.0 authorization code require each user to complete an individual consent flow. Aperture gives each user an isolated session and stores their tokens separately, so backends that tie state to a token never mix users.

Per-user connectors do not expose any tools until a user completes the OAuth authorization flow. On the first authenticated request, Aperture discovers and caches the connector's tool catalog. The catalog is not refreshed automatically and is only rediscovered after Aperture restarts (refer to capability discovery). Refer to the connectors reference for authentication requirements, scheme-specific fields, and provider-specific configuration parameters.

Capability discovery

Aperture keeps each MCP connector's tool and resource list current by polling the upstream every few seconds. When a remote server adds or removes a tool, Aperture updates its registrations and the change reaches connected clients shortly after. If a server becomes unreachable, Aperture unregisters its capabilities and re-registers them when the server recovers.

Per-user OAuth connectors are the exception. There is no shared-identity background poll because each user calls the upstream with their own token. Aperture loads a per-user connector's capabilities the first time any user completes consent and makes a request, then reuses that catalog. It does not poll per-user connectors in the background, so a change to the upstream's tools or to the connector's scopes is not picked up until Aperture restarts.

Access control

Aperture is deny-by-default for connectors, the same as for the rest of the gateway. Without a matching grant, a user sees no connector capabilities. Grants use "connectorID/category/resource" glob patterns, where the category is tools, resources, templates, or proxy. Aperture checks grants both when a client lists capabilities and when it invokes one, so a user can list and call only what their grants permit. Being a built-in system connector confers no special access. The grant system governs it like any other.

The proxy category governs the raw proxy path /v1/connectors/<id>/.... An MCP connector is also reachable through that path, and on it Aperture applies only the connector-level proxy grant, not the per-tool and per-resource filtering it applies on /v1/mcp.

How HTTP connectors stay safe

Because an HTTP connector forwards arbitrary client requests to an upstream with injected credentials, Aperture constrains the proxy to prevent credential leakage:

• It strips client-supplied Authorization and Cookie headers before forwarding, then injects the connector's own credentials.
• It strips Set-Cookie headers from upstream responses.
• It blocks all upstream redirects, which closes off credential exfiltration through redirect chains.
• It validates each upstream address against an SSRF-resistant dialer that rejects loopback, link-local, multicast, and other reserved or internal ranges, and it re-checks the resolved IP at connection time so a hostname cannot resolve to an internal address.
• It accepts only standard request methods (GET, POST, PUT, PATCH, DELETE, HEAD, OPTIONS), rejecting methods such as TRACE that would echo the injected credentials back to the client.

These rules mean an HTTP connector behaves like a narrow, credential-injecting gateway rather than a general-purpose proxy.

This shapes how failures surface. When an upstream is unreachable or errors at the connection level, Aperture returns a 502 Bad Gateway. A request that uses a disallowed method returns a 405. Very large responses are capped at a size limit and truncated, so a response that gets cut off may have exceeded that limit.

Current limitations

Connectors are in alpha, and a few behaviors are worth knowing before you rely on them:

• The connectors section requires the connectors feature flag.
• HTTP connector credentials are shared by every user with a matching grant. There is no per-user credential isolation for HTTP connectors.
• Dynamic registration is configured only through the legacy mcp section and has no connectors equivalent yet.
• Capability discovery for MCP connectors is polling-based, so there is a brief delay between an upstream change and its visibility to clients.
• Per-user OAuth connector capabilities are loaded once on first consent and are not refreshed until Aperture restarts.

Refer to the connectors reference for the authoritative list and for the deprecated mcp.servers migration path.

Related

• Get started with connectors to enable the feature flag and add your first connector.
• Connectors reference for complete field definitions, authentication types, and validation rules.