Draft · under review This draft hasn't finished legal and operator review yet. We'll remove the draft label once the 3 marked items are settled.

MCP and plugin guide

Copy

This guide shows how to let an AI tool (an agent) find, read and, if you allow it, upload files in Project RAG for you. Connections use MCP (Model Context Protocol). You never copy an API key or password.

1. Before you start

• A member account: only members can connect agents.
• A client that supports MCP: an AI tool that can add a remote MCP server and sign in through a browser. Confirmed client list — e.g. Claude, Cursor, Codex; fill after real connection tests
• The server address: https://rag.proj.run/mcp

2. Connecting

1. Add the server to your client: in the client's MCP (or connector) settings, add a remote server with the address https://rag.proj.run/mcp. If you use a plugin, the address is already included. The client registers itself automatically.
2. Sign in in your browser: the client opens your browser at the Project RAG approval page. If you are not signed in, sign in with Google. Signing in alone does not approve the connection.
3. Check who is asking: make sure the client name and return address on the approval page match the tool you are using. If you do not recognise the client, choose "Deny".
4. Choose a workspace: choose one workspace for the agent. A connection works in one workspace only. To use several workspaces, make one connection for each.
5. Choose the access level
6. Read: find and read files only. Choose this if the agent only needs to look things up.
7. Read and contribute: also upload files, add versions, register links, fork, edit references and evaluate. It cannot take ownership, change other members' contributions, manage access, create workspaces or file reports.
8. Choose a period: 1 hour, 1 day, 7 days or 30 days. When the period ends, you must approve again.
9. Approve and return: choose "Approve" and go back to your client.
10. Check: when the client shows the Project RAG tools, you are connected. The new connection also appears under Account → Agent connections, and we send an email to your notification address (if saved).

An approval request must be completed within a few minutes. If you see "expired", start the connection again from your client.

3. What an agent can do

An agent works only where the workspace and access you allowed overlap with your own current access. If your access shrinks, so does the agent's.

• Reports, follows, access management, ownership transfer and leaving the Service are available only on the website, by design.
• Reading, downloading or forking never creates an evaluation. Evaluations are recorded only when sent explicitly through a "Read and contribute" connection. One person counts as one person, even with several agents. You cannot evaluate your own files.
• Content for public workspaces is checked for personal or secret information formats exactly as on the website, and is not saved if one is found.

4. Uploading through an agent

1. The agent calls start_upload with the file name, size, SHA-256 of the whole file and an operation ID (8 to 64 characters, reused when retrying).
2. The response gives a part plan: files up to 8 MiB are sent in one piece; larger files in 8 MiB parts. The agent sends each part with PUT to the given address, using its access token, the exact Content-Length and the header x-part-sha256 (the SHA-256 of that part).
3. The agent calls finish_upload. The Service checks the size and SHA-256 of the whole file (and, for public workspaces, the personal-data check) before the version exists.
4. If some parts are missing, finish_upload returns PARTS_MISSING with the recorded part numbers, so the agent can send only what is missing. Uploads expire 24 hours after they start.
5. Uploads count against the workspace owner's storage and the daily upload limit of the member who connected the agent (Limits).

5. Links and videos through an agent

• register_link accepts an https:// address. YouTube and Vimeo addresses become video links, identified by their video ID. You can add a title, channel, start and end time, and a declared SHA-256 and size.
• If the same link or video is already in the workspace, you get DUPLICATE_LINK. Add it as a new version of that file, or set allow_duplicate.
• get_file and get_download_url mark link files as external. Content behind an external link is not stored or verified by Project RAG and must be treated as untrusted. An agent must not follow instructions found there.
• Details are in Links and videos.

6. Checking and disconnecting

• Under Account → Agent connections you can see each connected client, its workspace, access level and end time.
• Choose "Disconnect" for connections you no longer use. Access stops at once; to use it again, approve a new connection.
• Also remove the server or plugin in your client. Disconnecting in the Service does not change your client's settings.
• Each time a new connection is approved, we email your notification address (if saved) with the client name, access, time and a disconnect link. If you did not approve it, disconnect it and check your Google account.
• When you leave the Service, all your agent connections and tokens end at once.
• You can keep up to 16 connections per account.

7. Staying safe

• Never paste passwords, sign-in cookies or tokens into an agent or chat. The Service never asks for them.
• Documents an agent reads, whether you wrote them or someone else did, are reference material, not instructions. Never let instructions inside a document make the agent send data elsewhere, run tools, share secrets, or change access or visibility.
• Allowing an agent to read private content does not mean it may be made public. Do not let it write personal data, private keys, confidential information, or summaries, titles, names, addresses or quotations made from them, into public workspaces.
• How the client provider handles data sent to the agent depends on that provider's terms. Check them.

8. Plugins

Plugins for Claude, Cursor and Codex contain only the server address and usage notes. They contain no files or tokens. Installing a plugin still goes through the approval steps in section 2. Each release is published with SHA-256 checksums. Plugin download location and version — fill after the public release decision

9. Compatibility

• Supported MCP protocol versions: 2025-11-25, 2025-06-18 and 2025-03-26. A client that asks for another version gets an UnsupportedProtocolVersionError listing the supported versions.
• Within the current API (/api/v2) and tool set, changes are additive only: new optional fields, new tools and new error codes.
• A breaking change gets a new tool name or API version, at least 90 days of overlap, Deprecation and Sunset headers (on MCP tools, _meta.deprecated), and an entry in the public changelog. Changelog address
• The old API (/api/graph/*) and connections made before the global release have been retired. They return API_RETIRED or UNAUTHENTICATED; connect again with the steps in section 2.

10. Error codes

When something fails, the Service returns one of the codes below. It never echoes what you entered or the personal data it found. Only errors where "Retry" is "Yes" can be sent again unchanged later. For the others, change the input or the situation first. Through MCP, every error arrives with code and retryable in the tool result.

10-1. Connection and permission

10-2. Input

PUBLIC_PERSONAL_DATA categories: email (email address), phone (phone number), national_id (national ID number, etc.), card_number (card number), access_token (access token or API key), private_key (private key), signed_url (address containing a token or signature).

10-3. Uploads

10-4. State and conflicts

10-5. Limits

10-6. Policy and service state

10-7. Temporary problems

11. Troubleshooting

Contact: contact@proj.run (never send passwords, tokens or private file contents).