# Use organization bots with MCP

Use an organization bot to let autonomous agents read Falconer context without using a person's OAuth session.

Organization bots work with the native local MCP server, [`@falconer/mcp`](https://www.npmjs.com/package/@falconer/mcp). Use them for agent harnesses, sandboxes, CI checks, validation loops, and other read-only automation. Use OAuth instead when a human is operating the MCP client.

## Create the organization bot

Only organization owners can create organization bots.

1. Open Falconer.
2. Go to **Settings → Organization**.
3. Find **Bot API tokens**.
4. Click **Create bot token**.
5. Enter a clear bot name, such as `Local agent bot` or `CI validation bot`.
6. Copy the token when Falconer shows it. You will not be able to see it again.

![Organization settings showing the Bot API tokens section](/docs/images/org-bots-settings.png)

If a bot is no longer needed, delete it from **Bot API tokens** to revoke its access.

## Configure the bot

### Credentials file

The native `@falconer/mcp` server reads Falconer credentials from:

```text
~/.config/falconer/config.json
```

Create that file with the organization bot token:

```bash
mkdir -p ~/.config/falconer
chmod 700 ~/.config/falconer
cat > ~/.config/falconer/config.json <<'JSON'
{
  "apiKey": "sk_falconer_REPLACE_WITH_YOUR_BOT_TOKEN"
}
JSON
chmod 600 ~/.config/falconer/config.json
```

For local development or another Falconer deployment, add `baseUrl`. It should include `/api`, not `/api/v1`.

```json
{
  "apiKey": "sk_falconer_REPLACE_WITH_YOUR_BOT_TOKEN",
  "baseUrl": "http://localhost:3000/api"
}
```

Restart the MCP client after changing this file.

**CLI alternative:** Editing `~/.config/falconer/config.json` is the clearest setup for organization bots. If you prefer to let the Falconer CLI write the same file, use API-key login instead of OAuth:

```bash
npx @falconer/cli@latest login
```

The CLI may show a deprecation warning because OAuth is preferred for human users. Paste the organization bot token when prompted, then configure your MCP client to run `@falconer/mcp` as shown above.

### MCP client

Add the local Falconer MCP server to your MCP client config.

For project-scoped clients such as Claude Code, place this in `.mcp.json` at the project root:

```json
{
  "mcpServers": {
    "falconer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@falconer/mcp@latest"]
    }
  }
}
```

For Cursor, place the same server entry in `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "falconer": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@falconer/mcp@latest"]
    }
  }
}
```

If you install the package globally, you can use the binary directly:

```json
{
  "mcpServers": {
    "falconer": {
      "type": "stdio",
      "command": "falconer-mcp",
      "args": []
    }
  }
}
```

## Verify access

Ask your MCP client to search Falconer:

```text
Search Falconer for our deployment runbook.
```

Then read a specific document:

```text
Read this Falconer doc: <url>
```

If the bot has access, the client should return matching company-visible docs. If the bot tries to write, Falconer returns a read-only error.

## Access and permissions

An organization bot can search and read company-visible docs in its organization, including docs that inherit organization-wide view access. It does not inherit any person's private workspace.

Organization bots are read-only. Falconer rejects writes such as creating, updating, moving, or deleting docs; uploading media; changing permissions; or creating, editing, or resolving comments. Create separate bots for separate environments or agent roles.

## Rotate or revoke a bot

To rotate a bot credential:

1. Create a new bot token.
2. Replace the `apiKey` value in `~/.config/falconer/config.json`.
3. Restart the MCP client.
4. Delete the old token from **Bot API tokens**.

Deleting a bot token revokes it immediately.