Connect Claude Code over MCP

Before you start

Claude Code, installed and signed in. claude --version should print a version.
An Optic API key. Keys start with opt_. There's no self-serve signup yet: during early access we create a key for each person, and you'll see it once.
Your workspace slugs. One workspace per product, such as acme. The list_workspaces tool tells you which ones your key can use.

Add the server

claude mcp add --transport http optic https://api.optic.to/mcp \
  --header "Authorization: Bearer opt_..."

--transport http: Optic is a remote server over streamable HTTP. Nothing runs on your machine.
optic is the name Claude Code shows. If you hold keys for two accounts, add the server twice under different names, for example optic-acme and optic-northlight.
By default the server is added for the current project, for you only. Add --scope user to use it in every project.

Sharing the setup with a team

A project-scoped .mcp.json is meant to be committed, so never paste a key into it. Reference an environment variable instead, and give each person their own key:

{
  "mcpServers": {
    "optic": {
      "type": "http",
      "url": "https://api.optic.to/mcp",
      "headers": { "Authorization": "Bearer ${OPTIC_API_KEY}" }
    }
  }
}

Check the connection

claude mcp list

optic should show as connected. Inside a Claude Code session, /mcp shows the server's status and its tools. Then ask:

List my Optic workspaces.

Claude calls list_workspaces and answers with each workspace and your role in it.

Things to ask

You ask	Claude calls
What do I owe replies on today in acme?	`digest`
Any new signals above 0.7? Why did the top one score that high?	`list_signals`
What's waiting for my approval?	`list_approvals`
Dismiss that one, it's stock commentary.	`dismiss_signal`

Tools

Every tool except list_workspaces takes a workspace slug. Results come back as JSON; signals include the reasons behind their score.

Tool	Parameters	Status
`list_workspaces` Workspaces you can act in, with your role	`none`	Built
`digest` Replies you owe, conversations gone cold, tasks and deal next steps due	`workspace`	Built
`list_approvals` Drafts waiting for approval, with the person, company and triggering signal	`workspace, limit = 20`	Built
`list_signals` The signal feed, best score first, with the reasons behind each score	`workspace, status = "new", min_score = 0.0, limit = 20`	Built
`dismiss_signal` Mark a signal as not worth acting on	`workspace, signal_id`	Built
`approve / reject` Approve with edits; the original draft is kept for the edit-rate metric	to be announced	Building next
`search` People, companies and deals with filters	to be announced	Building next
`get_record` One record with its timeline	to be announced	Planned
`upsert_person / upsert_company` Create or update records, matched by email or domain	to be announced	Planned
`log` Add a note or task	to be announced	Planned
`move_deal` Change a deal's stage or next step	to be announced	Planned
`enroll / unenroll` Run a play on someone by hand	to be announced	Planned
`play_stats` Play performance for a period	to be announced	Planned

Permissions

Claude Code asks before it calls an MCP tool unless you've allowed it. The tools that exist today only read, or dismiss a signal, so they're safe to allow. When approvearrives, leave it off the allow list so every approval asks you first.

{
  "permissions": {
    "allow": [
      "mcp__optic__list_workspaces",
      "mcp__optic__digest",
      "mcp__optic__list_approvals",
      "mcp__optic__list_signals"
    ]
  }
}

The same thing over REST

The REST API uses the same keys and returns the same data.

curl -H "Authorization: Bearer opt_..." https://api.optic.to/v1/workspaces

Method and path	Same as
`GET /v1/workspaces`	`list_workspaces`
`GET /v1/workspaces/{workspace}/digest`	`digest`
`GET /v1/workspaces/{workspace}/approvals?limit=20`	`list_approvals`
`GET /v1/workspaces/{workspace}/signals?status=new&min_score=0.7`	`list_signals`
`POST /v1/workspaces/{workspace}/signals/{id}/dismiss`	`dismiss_signal`
`GET /health`	No key needed

Troubleshooting

"not authenticated" or HTTP 401: The header is missing or the key is wrong. It must be exactly Authorization: Bearer opt_....
A workspace isn't found: Check the slug with list_workspaces. Your key may be limited to a different workspace; a limit can narrow access but never widen it.
The server shows as failed in /mcp: Check that the URL ends in /mcp, then remove and re-add it: claude mcp remove optic.
A key leaked: Email hello@optic.to and we'll revoke it. Revoking one key doesn't affect anyone else's.