> ## 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={"dark"}
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`.

Operations come from an OpenAPI import.

**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. The servers that remain publish either a Streamable HTTP or an SSE remote, and the Portal tags each one with its transport. Pick a server tagged HTTP — Streamable HTTP is the only transport Noorle connects over.
</Note>

### Custom MCP

Your own MCP server, reached over **Streamable HTTP**.

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 | Available on |
| - | - | - |
| None | No credential | REST, MCP Registry, Custom MCP |
| Bearer | A token, encrypted at rest, sent as `Authorization: Bearer …` | REST, MCP Registry, Custom MCP |
| OAuth 2.1 | Authorization-code flow with PKCE | **Custom MCP only** |

REST and MCP Registry connectors take None or Bearer — that is the full set for
both. OAuth is not a form you fill in: the authorization and token endpoints
are discovered from the MCP server's own URL, so there is no provider to
configure by hand beyond authorizing.

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 — 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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.