Connectors and MCP

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.

catalog.py

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

OAuth2
Key
Endpoint

Authorization code with PKCE against an app you registered, or against an MCP server that publishes its own authorization server and registers clients dynamically.

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.

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, every OAuth connector uses that one shared redirect instead. Pass relay=False to keep a connector on its own callback.

For services where the user pastes a key.

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.

For services where the secret is the address, such as a private MCP link a merchant copies from their dashboard.

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

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.

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.

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.

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

{"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:

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.

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.

Sandbox and trust model

What isolates the bash tool, and what it does not cover.

Get started

Functions

Apps

Agents

Interface and users

Ship it

Guides

Reference

Resources

For LLMs

Connectors and MCP

Three kinds of grant

Where a grant lives

Calling a REST API

Microsoft 365

MCP servers

Loading tools on demand

Approvals

Directory copy

Next

Sandbox and trust model

​Three kinds of grant

​Where a grant lives

​Calling a REST API

​Microsoft 365

​MCP servers

​Loading tools on demand

​Approvals

​Directory copy

​Next

Sandbox and trust model

Three kinds of grant

Where a grant lives

Calling a REST API

Microsoft 365

MCP servers

Loading tools on demand

Approvals

Directory copy

Next