MCP Server
rp mcp runs a Model Context Protocol server, so that an AI agent can work with Repsy: list repositories and packages, read the vulnerability findings of a version, or show how to configure a package client. It works with Repsy Cloud and with a self-hosted Repsy Open Source, through the same profile rp uses for every other command.
The MCP client (Claude Code, Claude Desktop, Cursor, VS Code and others) starts rp mcp itself and talks to it over standard input and output. You do not run it by hand; you add it to the client’s configuration, as shown below.
- The credential decides what the agent can do. Three tools change the registry (create a repository, start a security scan, create a deploy token); the server offers them only while its credential may use them, and
--read-onlyhides them. - No tool deletes, revokes or rotates anything.
- MCP Tools lists every tool and its arguments;
rp mcp toolsprints the same list.
Before You Start
- Install
rp(see Installation) and note where it is:command -v rpon macOS and Linux,where rpon Windows. Desktop applications often do not see thePATHof your shell, so the configurations below use the full path; replace/usr/local/bin/rpwith yours. - Choose the Repsy host.
rp mcpuses the current profile (see Profiles and Hosts). To pin a host for the agent, add--hostname <host>to the arguments or setREPSY_HOST. - Choose a credential (next section).
rp mcpsigns every request withREPSY_TOKENwhen it is set, and with the credentialrp auth loginstored otherwise.
Credentials
Quick start: the stored sign-in. Run rp auth login once in a terminal and configure the client without a token. The browser sign-in lasts 24 hours, and the next rp auth login (on any machine) replaces it. When it expires, run rp auth login again: the running server picks up the new sign-in without a restart.
Durable setup: a personal access token. For an agent that runs every day, create a personal access token with only the scope it needs and give it to the client in REPSY_TOKEN:
rp token create --name mcp --scope repo:read --show-secret
repo:read is enough for every read tool, and with it the agent sees no write tool. Starting a scan needs repo:write; creating a repository or a deploy token needs repo:manage. Give the token those scopes only if the agent should write.
A token written into a configuration file is stored in plain text. Prefer the client’s way of keeping it outside the file where there is one (the ${...} references below), keep the file out of version control, and revoke the token with rp token revoke <id> when you no longer need it.
Configure Your Client
The snippets follow each client’s documentation as of November 2026. The clients ask before they use a new server and, by default, before a tool call; read what the agent is about to do before you approve it.
Claude Code
Add the server for all your projects:
claude mcp add --transport stdio --scope user repsy -- rp mcp
Everything after -- is the command Claude Code runs; add --read-only or --hostname <host> there. Options such as --env REPSY_TOKEN=... go before --, but that stores the token in ~/.claude.json; to keep it out of the file, export REPSY_TOKEN in the shell you start Claude Code from instead.
To share the server with a project, put it in .mcp.json at the project root. Claude Code expands ${VAR} there, so the token stays in each person’s environment:
{
"mcpServers": {
"repsy": {
"command": "rp",
"args": ["mcp"],
"env": {
"REPSY_TOKEN": "${REPSY_TOKEN}"
}
}
}
}
/mcp in Claude Code shows the server and its tools.
Claude Desktop
Open the configuration with Settings > Developer > Edit Config from the Claude menu of your system’s menu bar (not the settings inside the window). The file is ~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows and ~/.config/Claude/claude_desktop_config.json on Linux.
{
"mcpServers": {
"repsy": {
"command": "/usr/local/bin/rp",
"args": ["mcp"]
}
}
}
This uses the stored rp auth login. Claude Desktop has no documented way to read a secret from outside the file, so a token goes into env as plain text ("env": {"REPSY_TOKEN": "<token>"}). Quit and restart Claude Desktop after every change. The server’s messages are in mcp-server-repsy.log in Claude’s log folder (~/Library/Logs/Claude on macOS).
Cursor
Put the server in ~/.cursor/mcp.json (all projects) or .cursor/mcp.json (one project). Cursor expands ${env:NAME}, so the token stays in your environment:
{
"mcpServers": {
"repsy": {
"type": "stdio",
"command": "/usr/local/bin/rp",
"args": ["mcp"],
"env": {
"REPSY_TOKEN": "${env:REPSY_TOKEN}"
}
}
}
}
Leave out env to use the stored rp auth login.
VS Code
Run MCP: Add Server from the Command Palette and choose Command (stdio), or put the server in .vscode/mcp.json in the workspace (MCP: Open User Configuration opens the file for all workspaces). An input keeps the token out of the file: VS Code asks for it once and stores it securely.
{
"inputs": [
{
"type": "promptString",
"id": "repsy-token",
"description": "Repsy personal access token",
"password": true
}
],
"servers": {
"repsy": {
"type": "stdio",
"command": "/usr/local/bin/rp",
"args": ["mcp"],
"env": {
"REPSY_TOKEN": "${input:repsy-token}"
}
}
}
}
Leave out inputs and env to use the stored rp auth login. Copilot also reads a .mcp.json at the workspace root in the mcpServers format shown for Claude Code above.
Writes
Three tools change the registry. The server lists each one only while its credential may use it: a stored rp auth login may use all three, and an access token needs the scope in the table. The server checks the credential again while it runs and tells the client when the list changes, so a new rp auth login or another token takes effect without a restart. Start the server with --read-only (add it after mcp in the arguments) to hide them whatever the credential may do.
| Tool | Scope | What it does |
|---|---|---|
create_repo | repo:manage | Creates a repository, private unless the agent asks for a public one. A name that is taken is an error. |
trigger_scan | repo:write | Starts a security scan of a package version, or follows the one that is already running, and can wait up to five minutes for it. |
create_deploy_token | repo:manage | Creates a deploy token for a repository. The token is in the tool’s answer, so it ends up in the conversation and in the client’s history. Create deploy tokens with rp token create in a terminal when that matters. |
The whoami tool tells the agent whether a write tool is listed. Before rp 0.2.3 the write tools needed --allow-writes; the flag is still accepted, prints a warning and changes nothing.
Safety
Repsy bans an IP address for an hour when requests from it look like an attack (a path traversal, SQL or script text in a search, …) or when too many sign-ins fail. An agent can produce such a request by accident, for example by pasting a code fragment into a search. rp mcp therefore checks every request before it is sent:
- Arguments are checked first: a name with
.., a control character, a percent escape or a leading/is refused with an error that names the argument. - Every request is checked against the same rules the server applies, and is refused locally, with the rule it would break, instead of being sent. Since
rp0.2.3 everyrpcommand exceptrp apidoes this too (see Exit Codes). - A credential the server has refused is not sent again for a minute, and an expired browser sign-in is not sent at all. Sign in again with
rp auth login; the server picks it up without a restart. - A tool that the server answers only for a web panel session (
get_usage) refuses an access token without sending the request.
A failed call answers the same JSON error as rp --output json, with its code, and secrets are removed from every message.
Troubleshooting
- The client cannot start the server (
ENOENT, “command not found”): use the full path ofrpincommand. - Which host and user does the agent use? Ask it to call
whoami, or runrp auth statusin a terminal with the same environment. - The tool list:
rp mcp toolsprints it; MCP Tools describes each tool. - More detail: add
--debugaftermcpin the arguments. The requests (with secrets removed) go to the server’s standard error, which the client keeps in its MCP log.