# Connect an agent

> Connect Claude Code, Codex, Cursor, VS Code, Claude, ChatGPT, Gemini CLI or Windsurf to a Filement workspace over MCP.

Filement runs an [MCP](https://modelcontextprotocol.io) server for every workspace. An
agent connected to it can search, read, follow relationships and, if you allow it, create
and edit documents. It only ever sees what you can see in the app.

- **Server URL:** shown in **Settings → Agents**. On the hosted service it is the
  deployment's `…convex.site/mcp` address.
- **Transport:** Streamable HTTP.
- **One connection = one person + one workspace**, either read-only or read & write.

The server also ships **prompts**, saved workflows like "gather context on X" or "is
this document still current". Clients surface them as slash commands (Claude Code:
`/mcp__filement__research`) or in a prompt picker. See
[Tools and resources](https://filement.app/docs/agents/tools.md#prompts).

Settings → Agents in the web app has copy-ready snippets for every client below. Once you
create a token there, it fills the token into the snippets. Replace `<url>` with your
server URL.

Two ways to authenticate:

- **Sign in with your browser (OAuth).** Nothing to paste. The client opens Filement,
  and on the consent screen you pick the workspace and the access level. Use this
  wherever the client supports it.
- **Personal access token.** Create one in Settings → Agents and send it as
  `Authorization: Bearer <token>`. It is shown once. Use it for clients that only take
  headers, and for scripts and CI.

## Claude Code

```sh
claude mcp add --transport http filement <url>
# then inside Claude Code: /mcp → filement → Authenticate
```

With a token:

```sh
claude mcp add --transport http filement <url> \
  --header "Authorization: Bearer <token>"
```

## Codex CLI

```sh
codex mcp add filement --url <url>
codex mcp login filement
```

With a token:

```sh
export FILEMENT_TOKEN=<token>
codex mcp add filement --url <url> --bearer-token-env-var FILEMENT_TOKEN
```

or in `~/.codex/config.toml`:

```toml
[mcp_servers.filement]
url = "<url>"
bearer_token_env_var = "FILEMENT_TOKEN"
```

## Claude (web and desktop)

Settings → Connectors → Add custom connector. Paste the URL, press Connect, and approve.

## ChatGPT

Settings → Apps & Connectors → Advanced settings → turn on Developer mode. Create a
connector with the URL and OAuth authentication, then approve.

## Cursor

`.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):

```json
{ "mcpServers": { "filement": { "url": "<url>" } } }
```

With a token, add `"headers": { "Authorization": "Bearer <token>" }`.

## VS Code

`.vscode/mcp.json`. With this form VS Code asks for the token once and stores it
securely:

```json
{
  "inputs": [
    {
      "type": "promptString",
      "id": "filement-token",
      "description": "Filement token",
      "password": true
    }
  ],
  "servers": {
    "filement": {
      "type": "http",
      "url": "<url>",
      "headers": { "Authorization": "Bearer ${input:filement-token}" }
    }
  }
}
```

Leave out `inputs` and `headers` to sign in with OAuth instead.

## Gemini CLI

`~/.gemini/settings.json`, then `/mcp auth filement`:

```json
{ "mcpServers": { "filement": { "httpUrl": "<url>" } } }
```

## Windsurf

`~/.codeium/windsurf/mcp_config.json`:

```json
{
  "mcpServers": {
    "filement": {
      "serverUrl": "<url>",
      "headers": { "Authorization": "Bearer <token>" }
    }
  }
}
```

The server was tested end to end with scripted clients over both protocol versions, and
Claude Code and Codex were checked for which protocol they send (see
[Protocol versions](https://filement.app/docs/agents/developers.md#protocol-versions)). No snippet here has yet been run inside its
client against a deployment; they follow each client's documented config format.