# Connect your AI

> Give Claude Code, Codex, Cursor, ChatGPT or any MCP client its own governed access to your pod.

URL: https://doc.synap.live/docs/agents · Last reviewed against the code: 2026-10-20

An agent connects to your pod with its **own identity and key**. What it writes goes through the pod's governance:
by default its creates and edits apply directly and can be undone, while deletions, schema and structural changes,
and admin actions become proposals you approve. You can see and revoke each agent separately.

The user CLI, `@synap-core/cli`, does the wiring for you.

## The short path

```bash
npx @synap-core/cli init
```

`init` finds or creates your pod, approves this computer, and connects the agents it detects on it (Claude Code,
Codex, Cursor). See the [Cloud quickstart](/docs/start/cloud-quickstart).

## Connect one agent

```bash
synap connect claude-code
synap connect --list                          # everything that can be connected
synap connect cursor --workspace <id>         # focus on one workspace (default: pod-wide)
synap connect codex --project <id>            # focus on one project
```

`connect` creates the agent's identity on your pod, gives it a key, and writes the client's configuration. For
clients that read skill folders, it also installs the [Synap skills](/docs/agents/skills).

You choose how the agent's changes land: **Normal** (recommended: creates and edits apply directly with Undo;
deletions and structural changes ask you), **Creates only** or **Ask first**. `synap init` asks on the page where you
approve the computer; `synap connect claude-code` asks in the terminal. You can change it later on the agent's page
in the pod admin console. See
[Validation policy](/docs/concepts/validation-policy).

| Target | Client |
|---|---|
| `claude-code` | Claude Code (MCP and skills) |
| `codex` | OpenAI Codex (MCP and skills) |
| `cursor` | Cursor |
| `claude-desktop` | Claude Desktop |
| `chatgpt` | ChatGPT, with an API-key connector |
| `chatgpt-oauth` | ChatGPT, through Control Plane OAuth (no key to paste) |
| `raycast` | Raycast. See [Raycast](/docs/use/raycast). |
| `windsurf`, `zed`, `goose`, `opencode`, `openwebui`, `grok` | Those clients' MCP configuration |
| `vscode` | VS Code MCP extensions (Kilo Code, Cline, Continue, Copilot) |
| `aider` | aider |
| `generic` | Any other MCP client: prints a URL and key to paste |

## Clients you configure in a web UI

For ChatGPT, claude.ai and other clients configured in a browser:

```bash
synap mcp url --client chatgpt     # a dedicated key plus the URL and ready-to-paste snippets
synap mcp ui-setup cursor          # the exact form fields to fill in for a client
synap mcp connect-claude           # the claude.ai steps: paste a URL, approve in the browser
```

## Your own agent

For an agent you wrote yourself:

```bash
synap agents add --name researcher
```

prints an MCP URL and a key for a new agent identity named `researcher`. `--role admin|editor|viewer` sets its
workspace role (default `editor`).

## Check the connection

```bash
synap mcp verify    # is /mcp reachable, and is the key valid
synap doctor        # does each configured key work, and why or why not
synap whoami        # who the key acts as, and its scopes
synap agents list   # your agents on this pod
```

## What an agent can and cannot do

- It works through MCP or the Hub REST API, with the scopes and grant of its key. See
  [API keys](/docs/build/api-keys#limiting-an-agent) to limit what it may change.
- Its writes follow its write mode. Under the default, creates and edits apply directly with Undo; deletions and
  structural changes become proposals. Deletes, admin actions, scope changes, new kinds and roles, and new spaces,
  cells, playbooks and automations are always proposals, whatever rule you set.
- It can never approve a proposal, its own or anyone else's.
- It cannot create keys for other agents, widen its own approval rules, or give itself vault access.

## In this section

<Cards>
  <Card
    title="MCP"
    description="The MCP endpoint every pod serves, how clients authenticate to it, and what it exposes."
    href="/docs/agents/mcp"
  />
  <Card
    title="Agent skills"
    description="The skill packages that teach an agent how to work with a Synap pod, and how they are installed."
    href="/docs/agents/skills"
  />
</Cards>