Quickstart

From zero to a loaded task context in Cursor in under five minutes. One self-hosted server handles generation, caching, REST, and MCP. No install? Try UCP in the browser first.

0. Browser demo (no install)

Open ucpcore.org/try — paste any public GitHub issue URL. Curated mega-threads load instantly; other issues use the public demo API when deployed:

docker run --rm -p 8080:8080 -e UCP_DEMO_ENABLED=1 -e GITHUB_TOKEN=ghp_… \
  ghcr.io/ucpcore/ucp-server:latest

Demo endpoint: POST /v1/demo/generate with body {"ref":"owner/repo#123"} — rate-limited, GitHub only, CORS-enabled for ucpcore.org.

1. Start the server

Pick Docker or uvx. The server listens on port 8080 and exposes REST at /v1 and MCP at /mcp.

docker run --rm -p 8080:8080 -e GITHUB_TOKEN=ghp_yourtoken \
  ghcr.io/ucpcore/ucp-server:latest

uvx --from ucpcore-server ucp-server

Public GitHub issues work without a token (lower rate limit). For Jira, set JIRA_BASE_URL, JIRA_EMAIL, and JIRA_API_TOKEN on the server — see MCP reference.

2. Generate a package (optional check)

Verify the server with curl or use the CLI directly:

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

Without the server — CLI only:

pip install ucp-gen
ucp-gen github pallets/flask#5961 -o task.ucp.json

3. Connect Cursor

Add the MCP server to your Cursor config (mcp.json):

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

If the server runs with UCP_SERVER_API_KEY, add a Bearer header — details on the MCP page.

4. Add the `/ucp` command

Copy the ready-made command file into your project:

mkdir -p .cursor/commands
curl -sL https://raw.githubusercontent.com/ucpcore/ucp/main/libs/server/clients/cursor/ucp.md \
  -o .cursor/commands/ucp.md

Then in chat:

/ucp pallets/flask#5961

The agent calls generate_context, loads the package, and treats summary, must_know, decisions, and conflicts as authoritative task context.

5. LLM enrichment (optional)

By default generation is structural only — fast and deterministic. Add semantic synthesis with any OpenAI-compatible endpoint configured on the server (UCP_LLM_* env vars), then:

curl -s -X POST http://localhost:8080/v1/generate \
  -H 'Content-Type: application/json' \
  -d '{"source": "github", "ref": "microsoft/vscode#519", "llm": true}'

Next: full tool reference and environment variables on /mcp · package structure on /spec · sample JSON on /examples.