MCP & API

ucpcore-server exposes MCP over Streamable HTTP at /mcp and a REST API at /v1. Same process, same cache.

MCP tools

Tool	Parameters	Returns
`generate_context`	`source` (`github` \| `jira`), `ref` (`owner/repo#123` or `PROJ-123`), `llm` (optional, default `false`)	Builds a UCP; caches by id (e.g. `github-pallets-flask-5961`)
`list_contexts`	—	Cached packages: id, entity, title, freshness
`get_context`	`id`	Full UCP JSON
`get_context_markdown`	`id`, optional `token_budget`	Canonical Markdown rendering (SPEC §7)
`submit_usage_receipt`	Receipt JSON per SPEC §4.12 — `package_id`, `claims_cited`, `claims_ignored`, `outcome`	Records which claims helped; feeds warm ranking on the next generate

MCP prompts

Built-in prompts that clients may surface as slash commands:

Prompt	Action
`ucp_context(ref, llm=false)`	Generate a package and use it as authoritative task context
`ucp_catchup(ref)`	Generate and brief: decisions, conflicts, what's still open

Reference shape is detected automatically: owner/repo#123 → GitHub, PROJ-123 → Jira. In Cursor, prefer the project-local /ucp command for a first-class chat shortcut.

Cursor configuration

{
  "mcpServers": {
    "ucp": { "url": "http://localhost:8080/mcp" }
  }
}

With API key:

{
  "mcpServers": {
    "ucp": {
      "url": "http://localhost:8080/mcp",
      "headers": { "Authorization": "Bearer YOUR_KEY" }
    }
  }
}

REST API

Method	Path	Purpose
`POST`	`/v1/generate`	Generate package. Body: `{"source","ref","llm"?,"since"?,"audience"?}`
`GET`	`/v1/packages`	List cached packages
`GET`	`/v1/packages/{id}`	Full UCP JSON
`GET`	`/v1/packages/{id}/markdown?token_budget=1500`	Rendered Markdown
`POST`	`/v1/receipt`	Submit Usage Receipt (scope `receipt`). Body: receipt JSON referencing a cached `package_id`
`GET`	`/healthz`, `/readyz`	Probes (never authenticated)
`GET`	`/docs`	OpenAPI interactive docs

curl -s -X POST http://localhost:8080/v1/generate \
  -H 'Content-Type: application/json' \
  -d '{"source": "github", "ref": "pallets/flask#5961"}'

Environment variables

Variable	Default	Purpose
`UCP_SERVER_HOST`	`127.0.0.1`	Bind address (Docker image: `0.0.0.0`)
`UCP_SERVER_PORT`	`8080`	Bind port
`UCP_SERVER_API_KEY`	unset	Bearer auth for all endpoints except health probes
`UCP_CACHE_DIR`	`~/.cache/ucp-server`	Disk cache directory
`UCP_CACHE_TTL`	`900`	Cache TTL in seconds; `0` disables cache
`GITHUB_TOKEN` / `GH_TOKEN`	unset	Higher GitHub rate limits
`JIRA_BASE_URL`	unset	e.g. `https://yourcompany.atlassian.net`
`JIRA_EMAIL`	unset	Jira Cloud email (Basic auth)
`JIRA_API_TOKEN`	unset	Jira API token or PAT
`UCP_LLM_BASE_URL`	`https://api.openai.com/v1`	OpenAI-compatible endpoint for `llm: true`
`UCP_LLM_API_KEY`	unset	LLM key (falls back to `OPENAI_API_KEY`)
`UCP_LLM_MODEL`	`gpt-4o-mini`	Model name for enrichment

Stdio MCP (local files)

To serve pre-generated .ucp.json files from a directory — without the HTTP server:

pip install ucp-mcp
ucp-mcp --dir .

Exposes list_contexts, get_context, and get_context_markdown over stdio. No generate_context — generation is CLI (ucp-gen) or HTTP server.

Security

Set UCP_SERVER_API_KEY for any non-localhost deployment.
Clients pass references only — the server never fetches arbitrary URLs (no SSRF).
Request bodies capped at 64 KiB; unknown fields rejected.
Full notes: libs/server#security