# Glif - getting started

Glif's MCP/API surface is project-first. Calling agents should treat Glif as a server-side media agent, not as a model picker or a raw native-tool registry.

## Endpoint

~~~
https://glif.app/api/mcp
~~~

One endpoint, one fixed tool set for every authenticated client. JSON-RPC 2.0 over Streamable HTTP.

## Tools

- `compose_project` - create or continue a durable Glif project from natural language. Glif chooses models, native tools, and multi-step workflows internally. Pass `project_id` to continue; omit it to start a new project. For long-running work, pass an MCP task envelope (see Async jobs).
- `get_project` - inspect project status, active job, latest message, recent messages, and generated media (assets are included here).
- `view_media` - re-show already-generated media in the interactive viewer (e.g. "show me that image again"). Use this instead of pasting media URLs and possibly hitting CSP issues; it does not generate anything.
- `list_projects` - list recent projects owned by the authenticated user.
- `list_user_skills` / `get_user_skill` - read the authenticated user's personal Glif skills only. Global Glif skills are not exposed as public MCP tools.
- `upload_file` - upload image, video, or audio and pass the returned media URL into `compose_project` as an attachment/reference.
- `whoami` - returns identity, token label, plan, balance, and recent spend.

## Output shape

`compose_project` returns normal MCP content blocks:

- text blocks for the assistant response
- `resource_link` blocks for generated or referenced media
- a final JSON text block like `{ "project_id": "...", "job_id": "..." }`
- `_meta.glif` with `outputType`, `projectId`, `jobId`, `status`, and billing telemetry

Generated media is already displayed to the user via the `resource_link` blocks (and the media viewer on supporting hosts). Do NOT paste media URLs into your reply — to re-show or revisit earlier media, call the `view_media` tool. Only include a raw media URL when the user explicitly asks for one; if you do, note that their agent's sandbox may need its CSP / allowed-domains security settings adjusted to load it.

## Async jobs

Use `compose_project` with an MCP task envelope for long video/audio/multi-step work that may exceed a client's synchronous HTTP timeout. It is product-labeled as a job, but it uses MCP Tasks on the wire:

1. Call `compose_project` with a `task` envelope through the MCP Tasks flow.
2. Poll `tasks/get` until the task is terminal.
3. Fetch the final result with `tasks/result`.
4. Use the returned `project_id` with `get_project` or a follow-up `compose_project` call.

At-creation elicitation is supported when `prompt` is omitted and the client advertises elicitation. Mid-workflow `input_required` is not wired yet.

## What stays internal

Raw native model tools, memory writes, sim-state mutation, global Glif skills, and Glif harness state remain inside the Glif agent. The public API exposes projects, owned assets, user-owned skills, account status, and media results.

## Auth

OAuth 2.1 + PKCE. The server returns a 401 with a `WWW-Authenticate` header pointing at the OAuth protected-resource metadata; MCP-aware clients usually handle the browser authorization flow automatically.

Calling the endpoint directly over plain HTTP (no MCP client)? Send a `glif_v1_...` API token as `Authorization: Bearer <token>` instead — create one at https://glif.app/settings/api-tokens. See https://glif.app/api for the HTTP quickstart and OpenAPI spec.

## Example: compose_project

~~~json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "compose_project",
    "arguments": {
      "prompt": "a moody noir portrait of a sloth detective",
      "output_preference": "image"
    }
  }
}
~~~

Continue the project by passing the returned `project_id`:

~~~json
{
  "name": "compose_project",
  "arguments": {
    "project_id": "sim_abc",
    "prompt": "make it darker, add rain"
  }
}
~~~

## Help

- Live snapshot: call `tools/list`, `resources/list`, and `prompts/list` on the MCP server.
- Long-form reference: `docs/api-and-mcp.md` in the glif-graph repo.
- Feedback during preview: ping the Glif team.