# MCP & Agent API

## Auth

```
Authorization: Bearer <token>
```

- Personal token (`se_…` from /connectors) → acts as that user.
- OAuth access token (ChatGPT) → same as personal token.
- Legacy shared secret → may use `X-SkillEstate-Actor: user@micro.company` (admin only).

## MCP tools

| Tool | Purpose |
| --- | --- |
| `get_docs` | Read product/API docs (start with topic `agent`) |
| `list_skills` | Search/list skills (`q`, `tag`, `mine`, `page`) |
| `get_skill` | Skill + examples by id |
| `upsert_skill` | Create or update (match by title or `skillId`; `transferIfFound` optional) |
| `delete_skill` | Delete own skill |
| `transfer_skill` | Transfer ownership to another company email |
| `add_example` / `update_example` / `delete_example` | Manage examples |
| `normalize_tags` | Normalize tag strings |

## MCP resources

| URI | Description |
| --- | --- |
| `skillestate://docs/agent` | Agent playbook (Markdown) |
| `skillestate://docs/mcp` | This API reference |
| `skillestate://docs/connectors` | Connector setup |

## REST mirror

Base: `https://skill.estate/api/agent/v1`

Same bearer auth.

| Method | Path | Notes |
| --- | --- | --- |
| GET | `/skills` | Query: `q`, `tag`, `mine=1`, `page` |
| GET | `/skills/:id` | Skill detail |
| POST | `/skills` | Upsert body JSON |
| DELETE | `/skills/:id` | Owner delete |
| POST | `/skills/:id/transfer` | `{ "ownerEmail": "…" }` |
| POST | `/skills/:id/examples` | Add example |
| PATCH | `/examples/:id` | Update example |
| DELETE | `/examples/:id` | Delete example |

## Human docs

- HTML: [/docs](/docs)
- Raw Markdown: [/docs/mcp.md](/docs/mcp.md), [/docs/agent.md](/docs/agent.md)