# Agent setup (/developers/agent-setup)



This page is written for an AI agent that a person asked to set up Paragraph. If you're the agent, follow it from the top. To set things up yourself, see the [MCP server](/developers/mcp), [CLI](/developers/cli), and [API reference](/developers/api-reference), or open **Connectors → Agents** in the Paragraph app.

## Rules [#rules]

* Never print, log, commit, or ask for an API key in chat. When you need one, read it from the `PARAGRAPH_API_KEY` environment variable. If it isn't set, ask the person to create a key in the Paragraph app under **Settings → API keys** and set the variable themselves.
* Use only the official packages: `@paragraph-com/cli` on npm (its command is `paragraph`) and `paragraph-xyz/skill` for skills.
* Set up only the agent you're running in. Ask before a global install, `sudo`, or changing another app's settings.
* Keep tool approvals on.
* Drafts are fine. Ask before anything that publishes a post, sends an email, or deletes something.
* If you can't do a step yourself, give the person the exact step and wait.

## 1. Pick a path [#1-pick-a-path]

| The person wants                          | Path        |
| ----------------------------------------- | ----------- |
| Paragraph's tools inside this agent       | A. MCP      |
| Paragraph from a terminal, scripts, or CI | B. CLI      |
| Paragraph inside their app's code         | C. REST API |

If it's unclear, use A when you can add MCP servers, and C when you were asked to build something into a codebase. Otherwise, ask once.

## A. MCP [#a-mcp]

The server is `https://mcp.paragraph.com/mcp` (streamable HTTP). People sign in through the browser, so this path needs no API key.

| Agent             | Command or config                                                                                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Claude Code       | `claude mcp add --transport http --scope user paragraph https://mcp.paragraph.com/mcp`, then ask the person to run `/mcp` and sign in.                         |
| Codex             | `codex mcp add paragraph --url https://mcp.paragraph.com/mcp`. It opens the browser to sign in; `codex mcp login paragraph` signs in again.                    |
| Cursor            | Add `{"mcpServers":{"paragraph":{"url":"https://mcp.paragraph.com/mcp"}}}` to `~/.cursor/mcp.json`, then ask the person to sign in from Cursor's MCP settings. |
| VS Code (Copilot) | `code --add-mcp '{"name":"paragraph","type":"http","url":"https://mcp.paragraph.com/mcp"}'`                                                                    |
| Gemini CLI        | `gemini mcp add --transport http paragraph https://mcp.paragraph.com/mcp`, then `/mcp auth paragraph`.                                                         |
| Other             | Add a remote MCP server with the URL above. Most agents start the browser sign-in on their own.                                                                |

Where there's no browser, such as CI or a server, send the key in a header instead: `Authorization: Bearer $PARAGRAPH_API_KEY`. In Codex, for example: `codex mcp add paragraph --url https://mcp.paragraph.com/mcp --bearer-token-env-var PARAGRAPH_API_KEY`.

Agents usually load MCP servers when they start, so the person may need to restart you before Paragraph's tools appear.

## B. CLI [#b-cli]

1. Install it: `npm install -g @paragraph-com/cli` (Node.js 18 or later). On macOS, `brew tap paragraph-xyz/tap && brew install paragraph` also works.
2. Sign in: `paragraph login` opens the browser for the person to approve access. Without a browser: `echo "$PARAGRAPH_API_KEY" | paragraph login --with-token`.
3. Check it: `paragraph whoami`.

Add `--json` to any command for output you can parse, and set `PARAGRAPH_NON_INTERACTIVE=1` in scripts. For every command and its options, install the skill for the agent you're running in: `npx skills add paragraph-xyz/skill -a <agent>`, where `<agent>` is `claude-code`, `codex`, `cursor`, or `github-copilot`. Leaving out `-a` installs it into every agent on the machine.

## C. REST API [#c-rest-api]

* Base URL: `https://public.api.paragraph.com/api`
* Auth: `Authorization: Bearer <key>`, with the key read from `PARAGRAPH_API_KEY`
* Reference: [API reference](/developers/api-reference), and the OpenAPI spec at `https://docs.paragraph.com/openapi.json`

Keep the key in a git-ignored env file, such as `.env.local`. If the project has an example env file, add `PARAGRAPH_API_KEY=` to it with no value.

## Check that it works [#check-that-it-works]

Make one read-only call and report what it returned:

* MCP: call the `get-me` tool.
* CLI: run `paragraph whoami`.
* REST API: `curl -s https://public.api.paragraph.com/api/v1/me -H "Authorization: Bearer $PARAGRAPH_API_KEY"`

Name the tool or command you ran. If the person hasn't finished signing in, say so instead of reporting success.

## Hand off [#hand-off]

Tell the person what you set up, which files you changed, and anything left for them to do, such as signing in through `/mcp` or restarting the agent.