Skip to main content

​
API and MCP

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

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: 
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. bootstrap a workspace via HTTP
  2. create tokens and provider connections via HTTP
  3. validate readiness via HTTP capabilities
  4. create/apply plans via HTTP or MCP depending on client shape
  5. inspect runs and audit from the same normalized model