Coding agents and MCP

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:

Let the agent prepare a bounded, non-secret product brief from context it already has.
Pass only that brief to Custory with --brief or --stdin.
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

custory mcp install --client codex --workspace "Acme"
custory mcp verify --client codex

The CLI writes Custory MCP configuration to:

~/.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:

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

Install MCP for Claude

custory mcp install --client claude --workspace "Acme"
custory mcp verify --client claude

The CLI writes Custory MCP configuration to:

~/.claude.json

Existing mcpServers entries are preserved. The CLI updates the custory entry. Redacted generated entry:

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

Install MCP for Cursor

custory mcp install --client cursor --workspace "Acme"
custory mcp verify --client cursor

The CLI writes Custory MCP configuration to:

~/.cursor/mcp.json

Existing mcpServers entries are preserved. The CLI updates the custory entry. Redacted generated entry:

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

custory mcp install --workspace "Acme"

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

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:

~/.custory/mcp-installations.json

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

Verify the connection

Run:

custory mcp verify --client codex

Successful output looks like:

✓ 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:

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:

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:

custory init \
  --workspace "Acme" \
  --brief ./product-context.md \
  --journey recommended \
  --yes

Or pipe it:

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:

custory doctor

If the CLI is unauthenticated, run:

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 to see what agents can discover and call after MCP is installed.

Start here

Workflows

Reference

What this is

Why it matters

Install MCP for Codex

Install MCP for Claude

Install MCP for Cursor

Let the CLI detect the client

Workspace scoping

Config safety

Verify the connection

Uninstall

Safe prompt pattern for coding agents

Troubleshooting

Next step

​What this is

​Why it matters

​Install MCP for Codex

​Install MCP for Claude

​Install MCP for Cursor

​Let the CLI detect the client

​Workspace scoping

​Config safety

​Verify the connection

​Uninstall

​Safe prompt pattern for coding agents

​Troubleshooting

​Next step

What this is

Why it matters

Install MCP for Codex

Install MCP for Claude

Install MCP for Cursor

Let the CLI detect the client

Workspace scoping

Config safety

Verify the connection

Uninstall

Safe prompt pattern for coding agents

Troubleshooting

Next step