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

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

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

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	follows the composer’s Auto switch
destructive	asks in both modes

When a call needs approval, the model gets a stop and the user gets a confirm card naming the tool and the arguments. Approving binds to those exact arguments, so a changed call asks again. Each person can also set allow, ask or never per tool, and an organization admin can switch a connector off for everyone. 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.

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

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

​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

MCP servers

Loading tools on demand

Approvals

Directory copy

Next