# Plansmith for developers

The three developer surfaces, how they authenticate, and which one to reach for.



Everything your team does in Plansmith is available outside the browser.

<Cards>
  <Card title="CLI" href="/docs/developers/cli">
    Read and push plans from your terminal or from CI.
  </Card>

  <Card title="MCP server" href="/docs/developers/mcp">
    Give a coding agent the plan it is meant to build from.
  </Card>

  <Card title="API" href="/docs/developers/api">
    A versioned JSON API at `api.plansmith.co/v1`.
  </Card>
</Cards>

## Which one [#which-one]

Reach for the **CLI** for anything a person or a script runs: pulling a plan into a repo, pushing
from CI, checking what is Ready.

Reach for the **MCP server** when a coding agent should read the plan while it works. That is the
difference between an agent that guesses at requirements and one that builds from Specs with
acceptance criteria.

Reach for the **API** when you are building something of your own.

## One permission model [#one-permission-model]

Whichever surface you use, **your credential acts as you**. It reaches exactly the plans you can
reach, and a private plan nobody shared with you is invisible to your scripts and your agents too.

Nothing here can widen your access. A write-scoped key held by someone with view-only access to a
plan still cannot change that plan.

## Authenticating [#authenticating]

Two credential kinds work everywhere, on the same `Authorization: Bearer` header:

| Credential                     | Get one                                               | Use it for                                           |
| ------------------------------ | ----------------------------------------------------- | ---------------------------------------------------- |
| **Personal API key** (`psk_…`) | Settings → API keys, or `plansmith keys create`       | CI, scripts, anything non-interactive.               |
| **OAuth access token**         | `plansmith auth`, or your MCP client's consent screen | A person at a terminal, or an agent acting for them. |

A key is scoped `read` or `write`. Scope is a ceiling on top of your own permissions, never a
widening of them.

```bash
curl -H "Authorization: Bearer psk_read_…" https://api.plansmith.co/v1/me
```

## How things are addressed [#how-things-are-addressed]

Projects have a slug, plans are `PLAN-n` within their project, and Specs are `SPEC-n` within their
plan. They are the same handles you see in the web app, so a URL you read in the console is a path
you can call.

```text
/v1/projects/recipe-box
/v1/projects/recipe-box/plans/PLAN-12
/v1/projects/recipe-box/plans/PLAN-12/specs/SPEC-3
```