> ## Documentation Index
> Fetch the complete documentation index at: https://www.keycli.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API and MCP

> The canonical hosted control-plane API plus the current thin MCP adapter over the same service logic.

The product direction is simple:

* **HTTP API** is the canonical control-plane surface
* **MCP** is a thin adapter over the same service logic

If you are integrating Keycli into agents, tools, or demos, start with HTTP mentally even if you eventually expose MCP to an MCP-capable client runtime.

## Canonical hosted HTTP API

### Public endpoints

* `GET /health`
* `POST /v1/bootstrap`
* `GET /v1/capabilities`
* `POST /v1/workspaces/:workspaceId/github/webhooks/comments`

### Authenticated endpoints

* `GET /v1/me`
* `GET /v1/principals`
* `POST /v1/tokens`
* `POST /v1/connections`
* `GET /v1/connections`
* `GET /v1/connections/:id`
* `POST /v1/connections/:id/test`
* `POST /v1/plans`
* `GET /v1/plans`
* `GET /v1/plans/:id`
* `POST /v1/plans/:id/approve`
* `POST /v1/plans/:id/apply`
* `GET /v1/runs`
* `GET /v1/runs/:id`
* `GET /v1/audit`
* `GET /v1/state`

## Hosted API scripts

```bash theme={null}
npm run api:hosted
npm run worker:hosted
npm run db:init
```

## Storage modes

* no `DATABASE_URL` → in-memory mode, good for local demos
* `DATABASE_URL` set → Postgres-backed mode

When Postgres mode is enabled, the worker becomes part of the real execution story.

## Current MCP surface

Run the hosted MCP server with:

```bash theme={null}
npm run mcp:hosted
```

Current MCP tools:

* `whoami`
* `capabilities_list`
* `plan_create`
* `plan_get`
* `plan_list`
* `plan_approve`
* `plan_apply`
* `run_status`
* `run_list`
* `audit_list`

## Important current MCP truth

The MCP server is a **local stdio adapter** over the hosted service logic.

It uses environment-driven identity defaults such as:

* `KEYCLI_WORKSPACE_ID`
* `KEYCLI_PRINCIPAL_NAME`
* `KEYCLI_PRINCIPAL_KIND`
* `KEYCLI_PRINCIPAL_ROLE`

That means MCP is useful today for controlled integrations and demos, but it is **not** yet a claim of a fully productized remote auth/discovery story.

## When to use which surface

### Use HTTP when you want

* the clearest mental model
* explicit auth and token flow
* provider connection setup
* webhooks
* the most canonical product path

### Use MCP when you want

* agent-tooling compatibility
* a smaller tool vocabulary over the same service logic
* plan/apply/audit access inside an MCP-capable runtime

## Suggested integration order

1. `npm install`
2. start the hosted API with `npm run api:hosted`
3. bootstrap a workspace and token via HTTP
4. create provider connections via HTTP
5. validate readiness via HTTP capabilities
6. create/apply plans via HTTP or MCP
7. inspect runs and audit from the same normalized model

The legacy `keycli` installer / `src/cli.mjs` path is still useful for local prototype work, but it should not be treated as the canonical product onboarding surface.

## Related docs

* [Why Keycli](./concepts)
* [Provider connections](./provider-connections)
* [Approvals](./approvals)
* [First governed change](./first-governed-change)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.