> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usecustory.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Coding agents and MCP

> Connect Custory to Codex, Claude, or Cursor with the local CLI.

Use this page when you want an AI coding agent to work with Custory journey context from a supported MCP client.

## What this is

The local Custory CLI can install Custory MCP configuration for:

* Codex
* Claude
* Cursor

The generated client configuration points to Custory's MCP HTTP endpoint and uses a workspace-scoped bearer credential created through your existing CLI session.

## Why it matters

Coding agents often already know the product through the repository, docs, tests, or issue history.

The safe pattern is:

1. Let the agent prepare a bounded, non-secret product brief from context it already has.
2. Pass only that brief to Custory with `--brief` or `--stdin`.
3. Let Custory create or update journey context inside the workspace you choose.

Custory does not request GitHub OAuth, repository tokens, repository cloning, or repository access for this workflow.

## Install MCP for Codex

```bash theme={null}
custory mcp install --client codex --workspace "Acme"
custory mcp verify --client codex
```

The CLI writes Custory MCP configuration to:

```text theme={null}
~/.codex/config.toml
```

Existing non-Custory configuration is preserved. The CLI replaces only the `custory` MCP server block and keeps a backup when it updates an existing config file.

Redacted generated block:

```toml theme={null}
[mcp_servers.custory]
url = "https://api.example.custory/mcp"
http_headers = { Authorization = "Bearer cst_mcp_example" }
required = true
```

## Install MCP for Claude

```bash theme={null}
custory mcp install --client claude --workspace "Acme"
custory mcp verify --client claude
```

The CLI writes Custory MCP configuration to:

```text theme={null}
~/.claude.json
```

Existing `mcpServers` entries are preserved. The CLI updates the `custory` entry.

Redacted generated entry:

```json theme={null}
{
  "mcpServers": {
    "custory": {
      "type": "http",
      "url": "https://api.example.custory/mcp",
      "headers": {
        "Authorization": "Bearer cst_mcp_example"
      }
    }
  }
}
```

## Install MCP for Cursor

```bash theme={null}
custory mcp install --client cursor --workspace "Acme"
custory mcp verify --client cursor
```

The CLI writes Custory MCP configuration to:

```text theme={null}
~/.cursor/mcp.json
```

Existing `mcpServers` entries are preserved. The CLI updates the `custory` entry.

Redacted generated entry:

```json theme={null}
{
  "mcpServers": {
    "custory": {
      "type": "http",
      "url": "https://api.example.custory/mcp",
      "headers": {
        "Authorization": "Bearer cst_mcp_example"
      }
    }
  }
}
```

## Let the CLI detect the client

If only one supported client is clearly present, you can omit `--client`:

```bash theme={null}
custory mcp install --workspace "Acme"
```

If detection is ambiguous, the CLI asks you to provide:

```bash theme={null}
custory mcp install --client codex --workspace "Acme"
```

## Workspace scoping

MCP installation is bound to one accessible workspace.

If your account has access to one workspace, the CLI can use it automatically. If your account has multiple workspaces, pass `--workspace` with the workspace name, slug, or ID.

Use the slug or ID when workspace names are ambiguous.

## Config safety

When the CLI updates MCP configuration:

* existing non-Custory config is preserved
* the `custory` server block or entry is replaced
* existing config files receive a `.custory-backup-<timestamp>` backup
* writes are atomic
* config files are written with `0600` permissions where supported

Private MCP installation metadata is stored at:

```text theme={null}
~/.custory/mcp-installations.json
```

That metadata lets `custory mcp uninstall` revoke the tracked MCP credential when possible.

## Verify the connection

Run:

```bash theme={null}
custory mcp verify --client codex
```

Successful output looks like:

```text theme={null}
✓ Custory MCP is initialized with 12 tools and a valid workspace binding.
```

The exact tool count may change as Custory adds or removes public tools.

## Uninstall

Run:

```bash theme={null}
custory mcp uninstall --client codex
```

This removes the Custory entry from the client config and revokes the MCP credential when the CLI has installation metadata for it.

## Safe prompt pattern for coding agents

Use a prompt like this:

```text theme={null}
Summarize the product context needed to create a customer journey in Custory.
Include the product, target customer, activation path, important touchpoints,
known friction, and evidence gaps.
Do not include secrets, source code, credentials, customer PII, access tokens,
or internal-only implementation details.
Save the result as product-context.md.
```

Then pass the brief:

```bash theme={null}
custory init \
  --workspace "Acme" \
  --brief ./product-context.md \
  --journey recommended \
  --yes
```

Or pipe it:

```bash theme={null}
agent-command-that-writes-context | custory init \
  --workspace "Acme" \
  --stdin \
  --journey recommended \
  --yes
```

## Troubleshooting

If client configuration cannot be found, pass `--client` explicitly.

If verification fails, run:

```bash theme={null}
custory doctor
```

If the CLI is unauthenticated, run:

```bash theme={null}
custory login
```

If an existing Claude or Cursor config is malformed JSON, fix the JSON first, then rerun the install command.

## Next step

Read [Tools and agent tasks](/cli/tools-and-agents) to see what agents can discover and call after MCP is installed.