# MCP account access

Use this document when Codex, Claude Code, or another trusted AI agent must act through a user's Core account.

## Connect

Codex setup is one command:

```sh
npx -y @core-so/login@0.1.5 connect codex
```

It opens browser approval, stores the account connection outside the transcript,
and configures Core's first-party MCP adapter. Start a new Codex task after it
finishes.

Clients with working remote MCP OAuth can connect directly to:

```
https://core.so/mcp
```

For other clients, `npx -y @core-so/login --store https://build.core.so --client
<client-name>` is the fallback. It never prints the saved `core_mk_` credential.
Never paste one into a prompt.

## Choose a primitive

| Tool | Use when | Effect |
|---|---|---|
| `core_docs_search` | A stable public Core fact is needed. | Read-only. |
| `core_account` | Known structured account state is needed. | Read-only. |
| `core_ask` | A message or task needs the user's agent, context, workspace, or integrations. | Starts a durable task. |
| `core_tool_search` | A callable capability must be discovered. | Read-only. |
| `core_tool_invoke` | One exact search result should run. | Starts an asynchronous operation. |
| `core_operation_get` | An operation must be polled or resumed. | Read-only operation state. |
| `core_operation_cancel` | An operation must stop. | Cancels the named operation. |

Routing order: read structured state directly; search public docs for stable facts; delegate complex work with `core_ask`; search before invoking a tool.

## Operations

`core_ask` and `core_tool_invoke` return an `operation_id` and `task_url`. If the
user asked only to send or delegate, return the task link without polling. If
they asked for the result, poll the same id with `core_operation_get`. Supply a
stable `idempotency_key` when submission may be retried.

If state is `approval_required`, present the returned prompt and `approval_url` to the user. Poll the original operation after approval or denial. Approval is exact to one operation and is never inferred from an AI response.

## Credential classes

| Credential | Scope | Use |
|---|---|---|
| `core_mk_` | User account across its organizations; payer resolved per operation. | Trusted AI agent or harness using account MCP. |
| `core_sk_` | One project and spend grant. | Application code calling Core services. |

An authenticated agent can create a project key when a project needs it:

```sh
npx @core-so/login key create --project <project-name>
npx @core-so/login key run --project <project-name> -- <command>
```

## Related

- [Model router and project keys](https://docs.core.so/api-keys-and-inference.md)
- [Core Agent](https://docs.core.so/core-agent.md)