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, CLI, and API reference, or open Connectors → Agents in the Paragraph app.

RulesCopy Anchor Link

• 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 pathCopy Anchor Link

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. MCPCopy Anchor Link

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

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. CLICopy Anchor Link

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 APICopy Anchor Link

• Base URL: https://public.api.paragraph.com/api
• Auth: Authorization: Bearer <key>, with the key read from PARAGRAPH_API_KEY
• Reference: 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 worksCopy Anchor Link

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 offCopy Anchor Link

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.