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

# Connectors and MCP

> A user connects an account once, and the tools that need it get a live credential. OAuth, pasted keys, private endpoints and remote MCP servers.

A connector is a grant a person makes, for themselves or for a workspace, plus
the policy over the tools that use it. You declare it once, the directory renders
it, and the credential is attached server-side when a tool runs. Your code never
holds a token and neither does the browser.

```python catalog.py theme={null}
import cycls

notion = cycls.OAuth2(
    "notion",
    authorize="https://api.notion.com/v1/oauth/authorize",
    token="https://api.notion.com/v1/oauth/token",
    client_id=cycls.env("NOTION_CLIENT_ID"),
    secret=cycls.env("NOTION_CLIENT_SECRET"),
    scopes=["read_content", "update_content"],
    api="https://api.notion.com",
    api_headers={"Notion-Version": "2022-06-28"},
    scope="either",
)

web = cycls.Web().auth(cycls.Clerk()).connectors(notion)
llm = cycls.LLM().model("anthropic/claude-sonnet-4-6").connectors(notion)
```

Declare the same objects on both builders. `Web` serves the directory and the
connect routes, `LLM` decides whose tools the loop may offer.

## Three kinds of grant

> [tab] OAuth2
>
> Authorization code with PKCE against an app you registered, or against an MCP
> server that publishes its own authorization server and registers clients
> dynamically.
>
> ```python theme={null}
> github = cycls.OAuth2(
>     "github",
>     authorize="https://github.com/login/oauth/authorize",
>     token="https://github.com/login/oauth/access_token",
>     client_id=cycls.env("GITHUB_CLIENT_ID"),
>     secret=cycls.env("GITHUB_CLIENT_SECRET"),
>     scopes=["repo", "read:org"],
>     extra={"prompt": "consent"},
>     scope="user",
> )
> ```
>
> Tokens refresh when stale. The state that rides through the provider is signed
> and names the user and workspace, so the callback carries no JWT.
>
> For an MCP server that registers clients itself, pass `mcp=` in place of the
> endpoints and client. The endpoints are discovered and a client is registered
> once per organization, so there is no app to register and no secret to keep.
>
> ```python theme={null}
> salla = cycls.OAuth2("salla", mcp="https://mcp.salla.dev/mcp", scopes=["offline_access"], scope="either")
> salla_mcp = cycls.MCP("https://mcp.salla.dev/mcp").name("salla").connector(salla)
> ```
>
> For an app you register, the redirect URI is
> `https://my-agent.cycls.ai/connectors/{name}/callback`. When the deployment sets
> [`CYCLS_RELAY_URL`](https://docs.cycls.com/reference/environment#connector-relay), every OAuth
> connector uses that one shared redirect instead. Pass `relay=False` to keep a
> connector on its own callback.

> [tab] Key
>
> For services where the user pastes a key.
>
> ```python theme={null}
> posthog = cycls.Key(
>     "posthog",
>     hint="phx_...",
>     api="https://app.posthog.com",
>     auth="bearer",
>     scope="workspace",
> )
> ```
>
> `hint` is the field placeholder. Override `validate(value)` on a subclass to
> reject a malformed key before it is stored.

> [tab] Endpoint
>
> For services where the secret is the address, such as a private MCP link a
> merchant copies from their dashboard.
>
> ```python theme={null}
> zid = cycls.Endpoint("zid", host=".zid.sa", scope="workspace")
> ```
>
> `host` bounds what counts as a valid link, so a typo or an internal address is
> refused rather than dialed.

## Where a grant lives

```python theme={null}
cycls.OAuth2("gmail", ..., scope="user")        # personal, follows the person
cycls.Key("posthog", ..., scope="workspace")    # shared with the team
cycls.OAuth2("drive", ..., scope="either")      # the person chooses
```

A mailbox is a person, so `user`. A team analytics key is shared, so `workspace`.
`either` lets an admin connect one account for everyone while individuals can
still link their own.

## Calling a REST API

Give a connector an `api` base and no MCP server, and the loop offers one
`{name}_request` tool. The model builds a path, the platform attaches the
credential, and the host is bounded to that base. A call with a body is sent as
`content-type: application/json`.

```python theme={null}
linear = cycls.Key("linear", api="https://api.linear.app", auth="bearer")
```

The same relay backs `cycls.connector(name)` inside a generated app, so a
dashboard an agent builds can read live data without ever holding a key.

| Argument | Meaning |
| - | - |
| `api` | https base URL the relay is bounded to |
| `api_headers` | fixed headers the API requires on every call |
| `auth` | `bearer`, `basic`, `header` or `query` |
| `auth_name` | header or query parameter name when not bearer |

## Microsoft 365

Microsoft 365 works over the Graph REST API, with one connector per product so
each consent screen asks only for what that product needs. Register a multitenant
app in Microsoft Entra, add each connector's callback as a web redirect URI, and
add `MICROSOFT_CLIENT_ID` and `MICROSOFT_CLIENT_SECRET` to the container's
[environment](https://docs.cycls.com/reference/environment.md#inside-the-container).

```python theme={null}
outlook = cycls.OAuth2(
    "outlook",
    authorize="https://login.microsoftonline.com/organizations/oauth2/v2.0/authorize",
    token="https://login.microsoftonline.com/organizations/oauth2/v2.0/token",
    client_id=cycls.env("MICROSOFT_CLIENT_ID"),
    secret=cycls.env("MICROSOFT_CLIENT_SECRET"),
    scopes=["offline_access", "User.Read", "Mail.ReadWrite", "Mail.Send",
            "Calendars.ReadWrite", "Contacts.ReadWrite", "MailboxSettings.Read"],
    api="https://graph.microsoft.com/v1.0",
    api_headers={"Prefer": 'outlook.body-content-type="text"'},
    scope="user",
)

web = cycls.Web().auth(cycls.Clerk()).connectors(outlook)
llm = cycls.LLM().model("anthropic/claude-sonnet-4-6").connectors(outlook)
```

The `organizations` endpoints keep out personal Outlook.com accounts, and the
`Prefer` header returns mail bodies as text instead of HTML. The other products
use the same endpoints, client, `api` and `scope` with their own scopes:

| Connector | Scopes besides `offline_access` and `User.Read` |
| - | - |
| `outlook` | `Mail.ReadWrite`, `Mail.Send`, `Calendars.ReadWrite`, `Contacts.ReadWrite`, `MailboxSettings.Read` |
| `onedrive` | `Files.ReadWrite.All`, `Sites.Read.All` |
| `teams` | `Chat.ReadWrite`, `Team.ReadBasic.All`, `Channel.ReadBasic.All`, `ChannelMessage.Read.All`, `ChannelMessage.Send` |
| `onenote` | `Notes.ReadWrite` |
| `planner` | `Tasks.ReadWrite`, for Planner and To Do |

`ChannelMessage.Read.All` always needs an admin's consent.

## MCP servers

`cycls.MCP` connects to a remote MCP server. The harness speaks Streamable HTTP
itself, so every provider gets MCP, not just Anthropic. Tools are discovered once
and cached, and a session opens only when a tool is actually called.

```python theme={null}
server = (
    cycls.MCP("https://mcp.example.com/mcp")
    .name("example")
    .token(cycls.env("EXAMPLE_TOKEN"))
    .allow("search", "create_issue")
)

llm = cycls.LLM().mcp(server)
```

| Method | Meaning |
| - | - |
| `.name(alias)` | the name shown in the UI and used in the tool index |
| `.token(bearer)` | a fixed bearer token |
| `.connector(oauth)` | act with a user's grant instead of a fixed token |
| `.allow(*names)` | offer only these tools |
| `.guidance(text)` | extra prompt guidance for this server |
| `.writes(fn)` | classify which calls change something, for approvals |
| `.server_side()` | hand the server to the Anthropic connector instead, Anthropic models only |

## Loading tools on demand

A directory of connectors can hold hundreds of tools, and their schemas would not
fit in a system prompt. Each connector contributes one index line of about
fifteen tokens instead, and the model calls `find_tools` to load the schemas it
needs. Loaded tools stay for the rest of the conversation.

## Approvals

Every tool call is classified before it runs.

| Risk | Behavior |
| - | - |
| read | always runs |
| write | runs under Auto, asks under Manual |
| destructive | asks in both modes |

Each person picks Auto or Manual in Settings, General, Approvals, the row below
Connectors. It appears only when the deployment declares connectors. Auto is the
default, the choice is kept in the browser, and Manual is sent with each request
as `auto: false`, which your code reads as [`context.auto`](https://docs.cycls.com/agents/context#fields).

When a call needs approval, the model stops and a card asks above the message
box, where the agent's other questions appear. It asks about the action in plain
words and shows the connector's logo, or a trash can for a delete. Approving binds
to those exact arguments, so a changed call asks again. **Not now** is sent to the
model too. The conversation keeps one line where the call was: waiting, then how
it went (approved, done, failed, declined, or skipped when the person wrote
something else instead).

Each person can also set allow, ask or never per tool, including an API
connector's single request tool, and an organization admin can switch a connector
off for everyone. **Don't ask again** on a card sets that tool to allow. A tool set
to allow still asks before a destructive call.

A connector's CMS record words its calls with `actions`. Each entry matches a tool
by name, or an API connector's call by `METHOD path` with `*` for one segment, and
gives the card's question, a line under it, the button and the receipt, in English
and Arabic. `show` lists arguments to show as rows, read from the call or from its
JSON body, and an `id` puts one in the sentences as `{id}`. A call no entry matches
gets a plain question with the agent's own note on the call.

```json theme={null}
{"match": "POST me/sendMail",
 "ask": {"en": "Send this email?", "ar": "هل ترسل هذا البريد؟"},
 "button": {"en": "Send", "ar": "أرسل"},
 "done": {"en": "Sent to {to}", "ar": "أُرسل إلى {to}"},
 "show": [{"id": "to", "label": {"en": "To", "ar": "إلى"}, "from": "body.message.toRecipients"}]}
```

Deletes through bash are not destructive by default, because the sandbox shims
`rm` into a thirty day trash. Commands with nothing behind them, such as `shred`,
`mkfs` or `git push --force`, always ask.

## Directory copy

What the directory shows can come from your code or from a CMS, field by field,
with code winning. In code, these connector arguments set it:

| Argument | Shown as |
| - | - |
| `title` | the name, in place of the connector's `name` |
| `description` | the line under the name |
| `icon` | the logo URL. Without one, the website's favicon |
| `category` | the label under the name, and a filter in the directory |
| `prompts` | example prompts that fill the composer, with the connector mentioned |
| `about` | a paragraph on the detail page |
| `use_cases` | `(title, text)` pairs, listed under Use cases |
| `skills` | `(name, description)` pairs, shown as chips |
| `developer` | who makes the service |
| `website`, `privacy`, `terms`, `docs` | links on the detail page |

`title` and `description` also describe the connector to the model. To read copy
from a CMS instead, point `Web` at it:

```python theme={null}
web = cycls.Web().cms(
    brand="https://cms.example.com/agents/my-agent",
    connectors="https://cms.example.com/connectors",
    token=os.environ["CMS_TOKEN"],
)
```

This keeps behavior in Python, where it belongs, and copy in a CMS where a writer
can change it without a redeploy.

> [!WARNING]
>
> Connector objects are built on your machine and pickled into the deployment. Keep
> the declaration file free of functions and module-level values a callable would
> close over: a `writes` classifier or a tool handler must live in the file you
> deploy, not in an imported module.

## Next

> [card] [Sandbox and trust model](https://docs.cycls.com/agents/sandbox.md)
>
> What isolates the bash tool, and what it does not cover.


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