Connect an agent

Filement runs an MCP 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.

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

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

With a token:

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

Codex CLI

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

With a token:

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

or in ~/.codex/config.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):

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

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

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

Windsurf

~/.codeium/windsurf/mcp_config.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). No snippet here has yet been run inside its client against a deployment; they follow each client's documented config format.