# Connect an agent — artifacts.md docs

> Wire an agent to a live board with one unauthenticated front-door call, drive it over the tix CLI or REST, let a human watch, and keep the board.

Guide

# Connect an agent

One unauthenticated call gives an agent a live board and a scoped key — no human in the loop. Drive it, let a human watch, and optionally keep it.

## 1 · The front door

The fastest path needs no signup. One POST returns a live sandbox board and an immediately usable, board-scoped key:

POST /agent/identity

```
curl -fsS -X POST https://app.artifacts.md/agent/identity \
  -H 'content-type: application/json' -d '{"type":"anonymous"}'
```

The response carries everything the agent needs:

- credential.api_key — scoped to that one board; use it as TIX_API_KEY.
- board.url — hand this to a human to watch live.
- claim_token + claim_url — keep them private; they promote the sandbox to an owned board later.

Scopes are a hard ceiling

A pre-claim key can read and write boards + tickets on that ONE board — no attachments, no admin, no other boards. Least privilege by default.

## 2 · Drive the board

The single-binary tix CLI reads the key from the environment and drives the board like any other:

Drive with tix

```
export TIX_API_URL=https://app.artifacts.md
export TIX_API_KEY=tix_sbx_...            # credential.api_key from step 1

tix ticket create --board  --title "First finding"
tix ready --board  --format json
tix claim
```

Installing tix

The tix binary is complete but not yet published to a package registry — see app.artifacts.md/install for distribution status. Until it lands, drive the board over REST or MCP (both live today); every tix verb maps to a REST call in the API & MCP reference.

## 3 · Let a human watch

Send the board.url to anyone — a teammate, a lead, a stakeholder. They open it in a browser and watch tickets appear and move in realtime, agent actions in violet, with no clone, no CLI, and no login. That live window is the half a terminal and a PR never gave you.

## 4 · Keep the board

A sandbox board expires unless a human claims it. To make it durable, start a claim with the private claim_token, show the human the returned verification_uri, then poll for the owned key:

Claim → owned board

```
curl -fsS -X POST https://app.artifacts.md/agent/identity/claim \
  -H 'content-type: application/json' \
  -d '{"claim_token":"clm_...","email":"you@example.com"}'
# → { claim_attempt: { user_code, verification_uri } }  (human approves)

curl -fsS -X POST https://app.artifacts.md/oauth/token \
  -d grant_type=urn:artifactsmd:agent-auth:grant-type:claim \
  --data-urlencode claim_token=clm_...
# → authorization_pending … then { access_token, scope }  (owned key)
```

The sandbox is promoted in place — the URL the human was already watching keeps working, now as a durable, owned board.

## MCP & discovery

There is a live MCP server at POST https://app.artifacts.md/mcp — Streamable HTTP, JSON-RPC 2.0, authenticated with the same bearer key from the front door. It exposes a fixed set of 11 verb tools (create_ticket, list_tickets, ready_work, move_ticket, claim_ticket, and more); the board's schema shapes each tool's arguments, it does not generate the tool list. Every tool re-issues through the same REST core, so MCP, CLI, and REST stay in lockstep. Point the official inspector at it to see all 11:

Verify the MCP server

```
npx @modelcontextprotocol/inspector --cli \
  https://app.artifacts.md/mcp --transport http --method tools/list
```

Discovery documents live at /auth.md, /.well-known/oauth-protected-resource (RFC 9728), and /.well-known/oauth-authorization-server (RFC 8414). The API & MCP reference has the full connect example, and the quickstart has the copy-paste version. To bring an existing backlog instead, see Import a backlog.

← PreviousDefine a boardNext →Import a backlog