RAGfly — MCP Interface

Connect any MCP-compatible agent to your RAGfly organization's documents and capabilities. RAGfly uses the same MCP endpoint and OAuth authorization flow across clients; setup instructions differ only where each client exposes its own MCP settings. A bearer API key remains available for clients and scripts that need manual credentials.

An agent that has been handed an rf_… API key? Skip to the Agent runbook: download the setup script, read it, run it with the key on standard input, and ask the person to restart their client. The key and that restart are the only steps that need a human.

Opening original files from disk? Searching, asking and citing need no extra setup. To resolve a local original, use the per-document fs.home_var and fs.relative_path fields. The root variable can differ for each document; home_var: null means there is no local root to resolve. See Opening a document on disk.

Prerequisite

For the recommended OAuth setup, sign in to RAGfly during the client authorization flow; you do not need to copy an API key into the MCP client. For clients that do not support MCP OAuth, use an API key for your organization. See INTEGRATION.md § Credentials.

Create and revoke manual API keys in the RAGfly web app's API Keys page. A fixed-workspace key cannot change its workspace through MCP. A flexible key can select an authorized workspace with set_active_workspace or release focus with unset_active_workspace (or by passing null to set_active_workspace); RAGfly stores that focus on the server, so a new client using the same key sees it. MCP tools/list discovers MCP tools; list_operations reports the separate manifest operations allowed to the key.

MCP uses the same fixed English protocol as REST /v1: tool names, argument and result fields, public catalog codes, fixed enums, and API-authored messages and errors are English. OAuth discovery and protocol errors are English too; the browser consent screen is a human flow and may use the person's locale. Catalog values use their stored English aliases; if an alias is missing, the adapter returns a safe English error instead of the internal value or exception text. Document and organization-authored content keeps its original language.

ChatGPT web

ChatGPT web connects to RAGfly production at https://app.ragfly.ai/mcp using OAuth (connection verified on 2026-11-08).

All clients use the same MCP endpoint, tool catalog and user authorization. Connect with OAuth at https://app.ragfly.ai/mcp. Review the discovered tools and complete the RAGfly consent flow. Read and write operations enforce the connected user's permissions and active scope.

The previous read-only pilot endpoint /mcp-chatgpt has been retired. Reconnect at /mcp to authorize the common service. Tokens issued to the retired resource are rejected. Existing general clients at /mcp-http and legacy SSE clients at /mcp/sse remain compatible with the same MCP instance.

Transport and OAuth checks do not establish a completed ChatGPT UI connection. The client compatibility evidence below records the actual UI checks.

Connect from an MCP client with OAuth

Use this path when your client supports the MCP authorization flow. RAGfly's remote Streamable HTTP endpoint is:

https://app.ragfly.ai/mcp

The API-domain URL https://api.ragfly.ai/mcp remains compatible. Both production URLs use the same MCP instance, tool catalog and user permissions.

For TEST, configure https://test.ragfly.ai/mcp with OAuth. The web domain proxies the same TEST MCP instance and publishes matching protected-resource metadata. The previous Railway endpoint remains available for existing clients.

The client discovers OAuth metadata, opens the RAGfly sign-in and consent page, then stores the credential for later MCP calls. RAGfly records a revocable API key with origin OAUTH and the role, area and workspace you selected; review or revoke it at app.ragfly.ai/api-keys. When a client sends an OAuth resource, it receives an opaque bearer token bound to that MCP endpoint. The client does not need to inspect or transform it. OAuth does not change the tools or RBAC available at the selected endpoint. The credential follows its configured validity; RAGfly reports expires_in when it has an expiration. OAuth refresh tokens are not currently issued, so the client may need a new sign-in after expiration.

Client compatibility evidence

The following results are from specific client versions and RAGfly environments. They are observations, not a blanket compatibility guarantee. A successful connection in TEST or CORP does not establish behavior in PROD or in another product from the same vendor.

The setup instructions for other clients in this guide are configuration references; this table does not claim that every listed client/version has passed an end-to-end test. After OAuth, verify the connection with session and review the saved OAuth entry's displayed role and expiry in API Keys. If the saved values differ from the consent you approved, revoke that grant and reconnect.

VS Code workspace example:

{
  "servers": {
    "ragfly": {
      "type": "http",
      "url": "https://api.ragfly.ai/mcp"
    }
  }
}

Cursor example:

{
  "mcpServers": {
    "ragfly": {
      "url": "https://api.ragfly.ai/mcp",
      "auth": { "CLIENT_ID": "ragfly-cursor" }
    }
  }
}

GitHub Copilot in VS Code and Microsoft 365 Copilot are separate integration surfaces. VS Code connects directly to MCP. Copilot Studio can also add an MCP server as an agent tool where that feature is available in the tenant and agent harness; check its authentication flow in that environment. The separate Microsoft 365 API-plugin route packages REST operations with an OpenAPI description and a plugin manifest. OpenAPI is required for that API-plugin route, not for connecting to MCP from VS Code or a Copilot Studio MCP tool. See Microsoft's MCP tool setup and API-plugin setup.

OAuth and API key setup are two options

OAuth is the easiest route for clients with a browser-based MCP login. Use the existing API-key setup when a client does not implement MCP OAuth, or when an automated process needs a secret from its own secret store. Do not put a personal API key in a shared project config.

Set up with one command (API key)

For a client that cannot do the browser sign-in, or for an agent that has to be wired up unattended, one script does the whole setup and keeps the key out of every client configuration. It needs no Node.js and no Python. Download it, read it (it is short), and run it.

macOS / Linux (needs bash and curl):

curl -fsSL https://ragfly.ai/integradores/ragfly-mcp-setup.sh -o ragfly-mcp-setup.sh
bash ragfly-mcp-setup.sh --client claude-code --test   # asks for the key, no echo

Windows (Windows PowerShell 5.1 or later, already on Windows 10/11):

Invoke-WebRequest https://ragfly.ai/integradores/ragfly-mcp-setup.ps1 -OutFile ragfly-mcp-setup.ps1
powershell -NoProfile -ExecutionPolicy Bypass -File .\ragfly-mcp-setup.ps1 -Client claude-code -Test

It does four things:

1. Checks the key against GET /v1/session. A key that is rejected writes nothing.
2. Stores it in ~/.ragfly/ragfly-mcp.env (on Windows %USERPROFILE%\.ragfly\ragfly-mcp.env), readable only by you (mode 600 / a user-only ACL). Only the production environment is written. If the file already exists it is backed up and any other lines are kept.
3. Installs a launcher, ~/.ragfly/bin/ragfly-mcp.sh (Windows: ragfly-mcp.ps1), that reads that file and bridges the client's stdio to https://api.ragfly.ai/mcp-http/. The launcher holds no secret, and it lives outside the folders macOS protects from desktop apps (Dropbox, iCloud Drive, Documents, Desktop).
4. With --client (Windows: -Client), registers the launcher in your client: claude-code, codex or claude-desktop (it merges one entry into claude_desktop_config.json and keeps the rest). Without it the script prints the one line to add by hand, which is all any other MCP client needs: a stdio server whose command is the launcher (Windows: powershell.exe -NoProfile -ExecutionPolicy Bypass -File <launcher>).

So the key exists in exactly one place, ragfly-mcp.env. No client config, project file or command line ever carries it.

The key can also be given in the RAGFLY_API_KEY environment variable for the single run of the script (never as an argument, which other processes can read).

To rotate the key, run the script again with the new one. To remove the connection, revoke the key at app.ragfly.ai/api-keys and delete ~/.ragfly/ragfly-mcp.env.

What has been verified. On macOS: the Claude Code registration (claude mcp list shows ragfly connected), and the end-to-end session and tools/list calls through the launcher with a minimal environment and no Node.js installed. The Windows script was run end to end under PowerShell 7 on macOS against the real service (key check, storage, the launcher bridge, session returning authenticated: true, and the Claude Desktop config merge). It has not yet been run on a Windows machine, so three things are unverified there: the user-only file permissions (icacls), registering powershell.exe in each client, and the location of Claude Desktop's config on your install. The Claude Desktop entry is written in the format that client documents and the Codex registration uses codex mcp add … -- <command>; neither was run end to end inside its app.

Delegating this setup to an AI agent

Handing this page to an AI coding assistant (Claude, Codex, Cursor…) instead of doing it by hand? Here is exactly where it needs you — nothing more.

OAuth-capable client (the table above): the agent can add the server to its config by itself. The only manual part is the sign-in itself — the client opens a browser and only you can complete that login and consent. The agent never sees your password or the resulting key.

Manual API key (a client without OAuth, or an unattended process — a scheduled job, a personal agent running headless): minting a key needs a live human action in the web app, so the agent cannot do this one step. It should say so plainly rather than ask for your password. Your part:

1. Sign in at app.ragfly.ai/api-keys.
2. New key. Pick a role that grants only the actions it needs. For a bot identity instead of your own account, ask an administrator to create a PERFIL user for it first — that's the owner field in the same form.
3. Copy the rf_… value shown (once) and hand it to the agent.

Everything else from here — client config, role/area choice, session()/list_operations() verification, troubleshooting — the agent can do on its own.

Agent runbook: connect a client with an API key

For an agent that has been handed an rf_… key on a macOS, Linux or Windows machine. Nothing else needs to be installed (no Node.js). Never print the key, never put it on a command line that other processes can list, and never write it anywhere but ~/.ragfly/ragfly-mcp.env — the setup script does exactly that.

1. Pick the script for the machine. macOS / Linux: ragfly-mcp-setup.sh (needs bash and curl). Windows: ragfly-mcp-setup.ps1 (Windows PowerShell 5.1+, already installed).
2. Download and read it: curl -fsSL https://ragfly.ai/integradores/ragfly-mcp-setup.sh -o ragfly-mcp-setup.sh (Windows: Invoke-WebRequest https://ragfly.ai/integradores/ragfly-mcp-setup.ps1 -OutFile ragfly-mcp-setup.ps1).
3. Run it with the key on standard input, choosing the person's client: printf '%s\n' "$RAGFLY_KEY" | bash ragfly-mcp-setup.sh --key-stdin --client claude-code --test (Windows: $RAGFLY_KEY | powershell -NoProfile -ExecutionPolicy Bypass -File .\ragfly-mcp-setup.ps1 -KeyStdin -Client claude-code -Test; codex, claude-desktop, or omit the client option for any other client). The script validates the key first: a 401 means a wrong, revoked or other-environment key — stop and say so. A "could not reach" error is the machine's network or sandbox, not the key.
4. Restart if the client needs it. Claude Desktop reads its config only at startup: ask the person to quit it with Cmd+Q and reopen it — this also ends any session running inside the app, so finish other work first. In Claude Code, open /mcp or start a new session.
5. Verify. --test already called session through the launcher. After the restart, ask the person to open a new conversation and request session.
6. If it fails, ask for the last lines of the client's MCP log (Claude Desktop: Settings → Developer → Local MCP servers → View logs), match them against the troubleshooting table, and do not retry the same configuration unchanged.

Quick setup (manual API key)

No installation required. Add to your MCP client:

Claude Code — .mcp.json in your project

Export RAGFLY_API_KEY in the environment that starts Claude Code. Keep the key out of .mcp.json and version control. Claude Code expands variables in HTTP headers:

{
  "mcpServers": {
    "ragfly": {
      "type": "http",
      "url": "https://api.ragfly.ai/mcp",
      "headers": {
        "Authorization": "Bearer ${RAGFLY_API_KEY}"
      }
    }
  }
}

For a user-wide installation, use claude mcp add -s user instead of placing the file in a home directory. Restart Claude Code and check claude mcp list; an unset key may leave the server configured but unable to authenticate. Tools appear with the prefix mcp__ragfly__.

The Streamable HTTP endpoint is stateless: every request carries its own Authorization header and the server keeps no session, so a server redeploy does not drop your connection. It speaks MCP 2026-07-28 (one self-contained request, no initialize handshake) and the earlier handshake revisions (2025-11-25 and older); the client picks.

Claude Desktop chat — API key, no browser sign-in

Use this when you have an API key and want to talk to your documents from the Claude Desktop chat without signing in with an email (the Connectors screen only accepts a URL and OAuth; it has no field for a header). Claude Desktop starts a small local program, mcp-remote, that forwards every call to RAGfly with your key in the Authorization header.

Recommended: bash ragfly-mcp-setup.sh --client claude-desktop (Windows: ragfly-mcp-setup.ps1 -Client claude-desktop) does all of this for you, needs no Node.js, and keeps the key out of the config file (see Set up with one command). What follows is the manual form, which needs Node.js and stores the key in plain text inside claude_desktop_config.json.

You need Node.js 18 or newer (node -v) and your rf_… key. Open the config file (Claude Desktop → Settings → Developer → Edit config; on macOS it is ~/Library/Application Support/Claude/claude_desktop_config.json) and add the server under mcpServers, keeping whatever else is already in the file:

{
  "mcpServers": {
    "ragfly": {
      "command": "/absolute/path/to/npx",
      "args": [
        "-y", "mcp-remote@0.14.3",
        "https://api.ragfly.ai/mcp/",
        "--transport", "http-only",
        "--header", "Authorization:Bearer ${RAGFLY_API_KEY}",
        "--silent"
      ],
      "env": {
        "RAGFLY_API_KEY": "rf_xxxxxxxxxx",
        "PATH": "/absolute/path/to/node-folder:/usr/bin:/bin"
      }
    }
  }
}

• command must be the absolute path printed by command -v npx, and the first entry of PATH must be the folder that contains node (dirname "$(command -v node)"). A desktop app does not inherit your shell's PATH, so a Node installed through nvm, Volta, ~/local or similar is otherwise invisible to it.
• Write the header as Authorization:Bearer ${RAGFLY_API_KEY} — no space after the colon; mcp-remote expands the variable from env.
• The key sits in that file in plain text. Keep the file readable only by you (chmod 600 on macOS/Linux) and never copy it into a shared project or repository.
• Use the key with the endpoint shown above (api.ragfly.ai), the same service where you created it in the web app.

Quit Claude Desktop completely (Cmd+Q on macOS) and reopen it. Check Settings → Developer → Local MCP servers: ragfly should not show Failed. Then open a new conversation and ask Claude to call session; it should answer with your user, the active workspace and your access profile. From there, ask your questions in plain language — Claude picks search_documents, ask or the other tools by itself.

To rotate the key, edit RAGFLY_API_KEY in the same file and restart the app.

This configuration was verified on macOS. It has not been verified on Windows or Linux, where the file location and the way npx is launched differ.

Cursor / Cline / other MCP clients

For an OAuth-capable HTTP client, use the Streamable HTTP URL above and follow its authorization prompt. For an API-key setup, run ragfly-mcp-setup.sh (Windows: ragfly-mcp-setup.ps1) and register its launcher, ~/.ragfly/bin/ragfly-mcp.sh, as the server command (a stdio server, no key in the config). If the client can only talk HTTP and lets you set a header, use https://api.ragfly.ai/mcp with Authorization: Bearer <key>; keep that key out of any file you share. The legacy SSE URL (/mcp/sse) is not recommended: its session is lost on a redeploy.

Available tools

Setting up your organization — do this first

Four texts decide how well RAGfly serves you: a description and a system_prompt, at organization and at workspace level. The system prompt is injected into every skill with organization scope — the whole ingestion pipeline, not only chat — so an organization that leaves them empty ingests and answers worse than one that filled them in. Before the first load:

1. get_organization → if missing is not empty, there is work to do.
2. Read the customer's own website (you fetch it; RAGfly does not fetch URLs) and pass the text to draft_organization.
3. Review the draft — description is prose for humans, system_prompt is an instruction for the model — and send it with update_organization.

And before a large ingestion, get_usage says how much of each quota is left.

Tool names

Only the English names in the table exist. Retired tool aliases are not part of the public contract: calling one returns Unknown tool. The minimum compatible clients are Python SDK 0.4.0, TypeScript SDK 0.4.0 and CLI 1.20.0.

Always call session first to confirm the connection is valid, then list_operations to see what this key can do. Use get_operation for an operation's schema and run_operation to run it; a write_confirm operation returns a preview (executed: false) until you repeat the call with confirm=true after the person agrees.

For Retrieval, call search_documents and let your agent reason over the returned evidence. For Agentic Retrieval, call get_agent_context, use its system_prompt and limits, and invoke only tools declared in tools through run_agent_tool. Tool names are stable English public identifiers; names backed by catalog entries derive from their *_en aliases. The available list and argument schemas vary by identity/profile, so read them from the context at run time and pass the returned public_name unchanged. Never cache or persist the prompt or credentials; campaign artifacts should retain only system_prompt_hash and the per-layer hashes.

Document status values

LOADED · METADATA · SCANNED · CHUNKED · VECTORIZED · NOT_SCANNABLE · REVIEW

Opening a document on disk (fs block)

Document and search results may include an fs object. Do not infer how to open the source from origin or the shape of path alone. Follow this order:

1. is_cloud_only: true: the original remains in Google Drive or Dropbox. Never resolve the logical path locally. Use provider fields such as source_id or source_url when present and only with your own provider credentials.
2. is_public_url: true or origin: "PUBLIC": open the public URL directly.
3. is_absolute: true: open path directly on the machine where it exists.
4. Otherwise, when home_var names an environment variable, read that variable and join its value with relative_path. The variable is generated per root, so a corpus with multiple roots can return different names.

Example: two documents can resolve against separate local roots:

{
  "documents": [
    {"fs": {"home_var": "RAGFLY_HOME_442681", "relative_path": "Contracts/2026/a.pdf"}},
    {"fs": {"home_var": "RAGFLY_HOME_991203", "relative_path": "Legal/b.pdf"}}
  ]
}

Set each named variable on the machine running the agent:

export RAGFLY_HOME_442681="/Users/ana/Dropbox"
export RAGFLY_HOME_991203="/Volumes/Archive"

If home_var is null, empty, or its named variable is unset, there is no local root for that document. Do not fall back to a global root or guess from path. The document's indexed content remains available through RAGfly; use a public URL or provider access when the fs object supplies one.

A local path example:

{
  "fs": {
    "home_var": "RAGFLY_HOME_442681",
    "relative_path": "MyDocuments/lyrics/song.txt",
    "path": "/MyDocuments/lyrics/song.txt",
    "origin": "WEB",
    "is_absolute": false,
    "is_public_url": false,
    "is_cloud_only": false
  }
}

For this result, read RAGFLY_HOME_442681 and append MyDocuments/lyrics/song.txt. Check that the resolved path exists before opening it. Keep this variable local to the agent's environment; RAGfly does not read or store its value. See ENV_VARS.md.

Queue status values

A document's queue lifecycle: PENDING → IN_PROGRESS → COMPLETED / ERROR.

You may occasionally see WAITING, a transient internal state used while an orchestrated step waits for its dependencies. Treat it like IN_PROGRESS.

Example flow (agent)

# 1. Verify connection
session()
→ {"authenticated": true, "user": {"code": "bot-finance", "name": "Finance bot"},
   "active_group": "COMPANY", "active_workspace": "COMPANY", "profile": "USER", ...}

# 2. What can this key do?
list_operations()
→ {"operations": [{"code": "documents.get", "kind": "read", ...}, ...], "total": 18}

# 3. Ask over documents
ask(message="What are the penalty clauses in the 2024 contracts?")
→ {"answer": "...", "conversation_id": 512, "message_id": 514, "user_message_id": 513}

# 4. List vectorized documents
list_documents(status="VECTORIZED", limit=10)

# 5. Run a skill over a collection
run_skill(skill_code="SUMMARIZE_DOCUMENT", collection_id=42)

# 6. Monitor progress
queue(status="IN_PROGRESS")

Permissions

Each tool operates in the context of the API key's user — same RBAC as the web interface. list_operations and catalog show what the key can reach; a tool outside that reach fails with a 403 in the tool error. Role identifiers are not returned by the public interface; use the available operations to understand the key's access.

Troubleshooting

Codex

Codex supports both OAuth and bearer API-key authentication for remote MCP. In the desktop app, use Settings → Complementos → MCP → Agregar → Conectar con un MCP personalizado, select HTTP secuenciable, and enter https://api.ragfly.ai/mcp. The browser sign-in creates and stores the RAGfly credential for this MCP connection.

The CLI can configure and authorize the same remote endpoint:

codex mcp add ragfly --url https://api.ragfly.ai/mcp
codex mcp login ragfly
codex mcp list

For API-key authentication, either run bash ragfly-mcp-setup.sh --client codex (Set up with one command), or use:

codex mcp add ragfly \
  --url https://api.ragfly.ai/mcp \
  --bearer-token-env-var RAGFLY_API_KEY

See QUICKSTART.md for the full walkthrough and direct REST alternative.

Practical differences