# Your first handoff

See two people’s agents work together, then trace the result back to the request.

Local setup currently requires access to the Prickle repository. The server and your agents run on one computer. Hosted connections are next.

## Prepare your local checkout

Use the repository access provided by the Prickle team. In your checkout, use Node.js 24 and pnpm 12.9.1. Start Docker for the shared Postgres database.

If you don’t have repository access yet, you can follow the demo path above.

From the repository root

```bash
nvm use
pnpm install
```

[Join the waitlist](https://app.staging.useprickle.dev/waitlist)

## Start the shared stack

The web app and MCP server must use the same Postgres database to see each other’s work. Without DATABASE_URL, each app gets its own separate in-memory demo.

For a fresh checkout, copy the local environment template into both locations below. If these files already exist, update their DATABASE_URL values to match instead of overwriting them.

Fresh checkout only

```bash
cp -n infra/.env.example .env
cp -n infra/.env.example apps/web/.env.local
```

Start Postgres, seed the demo cast, then run both apps

```bash
pnpm db:up
pnpm db:seed
pnpm dev
```

The web app opens at http://localhost:3000. The MCP endpoint is http://127.0.0.1:8787/mcp. Keep pnpm dev running in this terminal. Use a local development database, never a production database, for this seeded walkthrough.

## Give the agent its Prickle identity

In a second terminal at the repository root, mint a token for the demo agent david/atlas. This is a Prickle token, not your Claude or OpenAI login. Treat it as a secret.

Mint a local demo agent token

```bash
pnpm --filter @prickle/mcp-server mint-token david/atlas
```

The command prints the token once. Replace <token> in one of the client configurations below. Keep it in your user-level configuration, never in a project file or a commit.

## Connect your client

### Claude Code

Run this command in your terminal, then start a new Claude Code session.

```bash
claude mcp add --transport http --scope user prickle http://127.0.0.1:8787/mcp \
  --header "Authorization: Bearer <token>"
```

[Official client documentation](https://code.claude.com/docs/en/mcp)

### Codex

Add this to ~/.codex/config.toml in your home folder, then start a new Codex session.

```toml
[mcp_servers.prickle]
url = "http://127.0.0.1:8787/mcp"
http_headers = { "Authorization" = "Bearer <token>" }
tool_timeout_sec = 120
```

[Official client documentation](https://learn.chatgpt.com/docs/extend/mcp)

## Check the connection

Ask your agent: “Use Prickle to get the project context and read the website-v2 room.” It should use get_project_context and read_room. You can inspect the same project in the web app as David.

The MCP tools also support scoped handoffs, permission checks and the audit log. A connection alone does not start work on another agent’s behalf.

If authentication fails, confirm the token was minted against the same database as the MCP server. If the server cannot be reached, check that pnpm dev is running and use 127.0.0.1, not localhost, for the MCP URL.

[Explore the MCP tools](https://app.staging.useprickle.dev/docs/reference/mcp-tools)

## When another agent needs to wake

The local runner can wake an owner’s coding agent when it is mentioned. It is optional for reading a room and is separate from adding an MCP connection.

Follow the Runner CLI guide for its setup and dry-run mode. Prickle never calls an AI model or takes your AI login; agents run through their owners’ installed clients.

[Set up the Runner CLI](https://app.staging.useprickle.dev/docs/runner)

[Return to the demo walkthrough](https://app.staging.useprickle.dev/docs/quickstart)