> ## Documentation Index
> Fetch the complete documentation index at: https://noorle.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Connectors

> Three ways to reach an external system — a REST API, a server from the MCP registry, or your own MCP server — with credentials encrypted at rest

A **connector** points a capability at something that already exists somewhere else. No code, no deployment: you describe the endpoint and how to authenticate, and its operations become tools.

## The three kinds

```mermaid theme={null}
graph TD
    Conn["Connector"]
    Conn --> R["REST<br/>base URL + operations<br/>OpenAPI import supported"]
    Conn --> M["MCP Registry<br/>a published server,<br/>by name and version"]
    Conn --> C["Custom MCP<br/>your own server,<br/>over Streamable HTTP"]
```

### REST

A REST connector is a base URL plus a list of operations. Each operation has a name, description, HTTP method, path template, an input schema, an optional output schema, parameter mappings, and an optional response transform.

Supported methods: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`.

You can define operations by hand, or import them.

**OpenAPI import** accepts **OpenAPI 3.x and Swagger 2.0**. Anything else is rejected as an unsupported version. The base URL is taken from `servers[0].url` for 3.x, or from `schemes`/`host`/`basePath` for 2.0.

Common headers can be attached to every request on the connector, and stored encrypted.

### MCP Registry

Point at a server published in the public MCP registry, by registry name (`io.github.owner/server-name`) and version. The connector stores the server's own descriptor and its transport configuration.

Registry access is **read-only** and goes through a mirror of `registry.modelcontextprotocol.io` refreshed every six hours. Noorle does not host or run these servers.

<Note>
  The registry contains servers that only ship a **stdio** transport. Those are filtered out of what Noorle offers — Noorle dials out over Streamable HTTP and does not execute server processes.
</Note>

### Custom MCP

Your own MCP server, reached over **Streamable HTTP**. Environment variables can be attached and are stored encrypted.

There is no SSE client transport and no stdio execution in the connector path. If your server only speaks stdio, it needs an HTTP front to be reachable.

## Authentication

| Method    | Shape                                                         |
| --------- | ------------------------------------------------------------- |
| None      | No credential                                                 |
| Bearer    | A token, encrypted at rest, sent as `Authorization: Bearer …` |
| OAuth 2.1 | Client id, client secret, scopes, and stored token data       |

For OAuth, the only provider type available is **Custom** — you supply the authorization URL and the token URL yourself. There are no pre-configured providers.

A connector shows as **needs auth** in exactly two situations: OAuth is configured but no token has been obtained yet, or dynamic client registration is in flight and the auth configuration has not landed.

Token refresh happens under a distributed lock, so concurrent calls do not race to refresh.

## Credential handling

All secret material — bearer tokens, client secrets, common headers, environment variables — is stored as AES-256-GCM ciphertext. It is decrypted at the point of use and is never returned by any read API.

## Idempotency

A connector may declare where Noorle should put a stable idempotency key: an HTTP header of your choosing, or a field in MCP request metadata. If it declares neither, no idempotency key is sent — the provider makes no claim about replay safety and Noorle does not invent one.

## How connector tools appear

Once bound, a connector's operations are namespaced like any other capability and appear in `tools/list` alongside built-ins and plugins. Nothing about the calling convention differs.

Every connector tool is classified at the **Act** risk tier, kind-wide. The platform cannot see inside a third-party API to tell a read from a write, so it does not pretend to. Under Supervised autonomy that means connector calls pause for approval until you auto-approve them.

## Choosing between a connector and a plugin

|                    | Connector                    | Plugin                              |
| ------------------ | ---------------------------- | ----------------------------------- |
| Code to write      | None                         | Yours, compiled to WebAssembly      |
| Runs where         | The provider's servers       | Noorle's WASM sandbox               |
| Network dependency | Yes                          | Only what you allowlist             |
| Best for           | Systems with an existing API | Logic you own and want kept private |

If the system already has an API, use a connector. Write a plugin when the behavior itself is the thing you are adding.

## Where connectors live

In the Portal, connectors are their own section under **Capabilities**. Bind them to agents from the agent's Capabilities section, and to gateways from the gateway's Capabilities view.

## Practical notes

* Credentials are per connector. Two gateways bound to the same connector share its credential; two connectors pointed at the same API do not.
* A connector's tool list is fetched from the upstream server and cached. When an upstream server changes its tools, connected clients are **not** notified — Noorle never emits `notifications/tools/list_changed`.
* Least privilege applies at the provider: create the narrowest API key the provider offers, not an admin token.

***

Next: [Memory System](/docs/learn/concepts/memory-system) — how an agent keeps context across turns.