Connect to the Prepr MCP server
Add the Prepr MCP server (
) to the user's agent, get it
authorized, and prove it works with one read-only call.
First run the check. If Prepr tools
are already present, say so, name the environment, and stop.
Step 1: Detect the client
Use the agent you are running in when you know it. Otherwise look for
or
,
,
,
, and
in the project. If more than one client is in use, ask which
ones to configure. If nothing points to a client, ask.
Then look for an existing
entry in every place the client reads:
- Claude Code: the project , and (local and
user scopes in take precedence over the project file).
- VS Code: and .
- Cursor: . Codex: . OpenCode:
.
Step 2: Choose the auth route
- OAuth (default): Claude Code, Claude Desktop, Cursor, Codex, OpenCode,
VS Code, ChatGPT. The user signs in to Prepr in the browser and picks an
environment. Their Prepr role permissions apply.
- Token: GitHub Copilot CLI, or any client where the user says OAuth is
not available. Tokens are issued by Prepr Support.
Recommend picking a Scratch environment for a first try. Writes go to
whatever environment is chosen when signing in, and a Scratch environment
makes it safe to see what the skills do.
Step 3: Write the config
Use the snippet for the client from
clients.md. A
project-root
serves Claude Code and VS Code at once for OAuth; see
the note at the top of clients.md. Copilot CLI is token-only and gets its own
entry named
.
- Merge into the existing file. Keep other servers exactly as they are.
- If an existing HTTP entry is present (for example with the old
URL), update it in place in the file where it lives, even if that is
not the file you would pick for a new entry: URL, headers, and the client's
required . Never leave two entries that the same client reads.
- If the existing entry is a stdio or entry (a instead
of a ), replace the whole entry, and only after the user agrees.
Otherwise print the snippet.
- If an existing entry holds a literal token, never print it: mask it as
in anything you show. Replace it with the env-var reference and
advise the user to rotate the token, since it has been stored in a file.
- If the file cannot be edited safely (JSON with comments, or an entry in a
shape you do not recognise), do not touch it. Print the snippet and tell the
user where it goes.
- Write project-level files directly. Never write a user-level file that
would hold a token; give the user the command from clients.md instead
(Copilot CLI).
- Claude Desktop and ChatGPT have no file. Give the steps from clients.md.
Step 4: Token route only
- The config references in the client's own syntax. Never
ask for the token, never write it into any file, never echo it.
- Tell the user how to get one: email support@prepr.io and name the Prepr
environment it is for.
- Tell them to set it in their shell profile (for example
export PREPR_MCP_TOKEN=...
Step 5: Authorize and verify
- Give the one authorize step for the client (from
the check). Mention that OAuth
asks them to pick an environment, and that changing environment later
means authorizing again.
- Ask the user to say when they are done. Some clients need a restart or a
reload to pick up the new server.
- Call for the environment's name and domain, then
(first page only, read-only). Report the environment and
how many models it has. If the tools are still missing, go back to
the check and report which state
you are in.
- If the project's front end has its own Prepr GraphQL URL or token (for
example in ), check that it reads the same environment as MCP:
compare one item's id through both. A different environment means
schema and content changes made through MCP will not show in the app or
in its generated types. Never print the token while you check.
Step 6: Allow read-only tools (Claude Code)
Each Prepr tool asks for permission the first time, which blocks the checks
above in a non-interactive session. Offer to allow the read-only tools in the
project's
under
:
mcp__prepr__get_initial_context
,
,
mcp__prepr__get_schema_entity
,
,
,
. Write this only after the
user agrees, merge with existing entries, and never allow write tools or a
wildcard: every write must keep asking.
Step 7: Mention the environment AI context
also returns the environment AI context. If it is
empty, say once that filling it helps every AI request, and offer to draft it
(see
ai-context.md).
Step 8: Recommend a safety setting
Tell the user once: for production, an administrator can switch off schema
writes and deletes for all MCP requests under
Settings → Integrations → MCP Server, while keeping them on in development.
What's next
Offer the next step that fits: design a content model (
),
review the existing schema (
), keep the schema in Git
(
), or work with content (
).