RAGfly — MCP Interface

Connect any MCP-compatible agent to your RAGfly group'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.

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 group. See INTEGRATION.md § Credentials.

Create and revoke manual API keys in the RAGfly web app's API Keys page. A fixed-entity key cannot change its entity through MCP. A flexible key can select an authorized entity with set_active_entity or release focus by passing null; 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 tenant-authored content keeps its original language.

ChatGPT web — private TEST pilot

RAGfly's dedicated ChatGPT MCP endpoint currently runs in TEST. It exposes only session and search_documents; the server rejects other tools. A production ChatGPT connection is not available yet. Do not configure the general /mcp-http/ endpoint in ChatGPT: that endpoint also offers write-capable tools.

The private pilot requires an eligible ChatGPT account, OAuth consent and a synthetic TEST document approved for the trial. The pilot operator verifies Scan Tools shows exactly the two read tools, checks a cited result and revocation, and only then prepares production availability and a public setup guide. Ask your RAGfly contact to join the pilot rather than entering a production endpoint that has not been released.

When the pilot is available, a question sent through ChatGPT reaches RAGfly and matching excerpts, document names and citations return to the ChatGPT conversation. RAGfly may send the query and candidate excerpts to the configured reranking provider. Revoking OAuth stops future requests but cannot remove text already returned to ChatGPT. Review your workspace's data controls and the provider terms before connecting sensitive documents.

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://api.ragfly.ai/mcp-http

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 entity 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.

VS Code workspace example:

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

Cursor example:

{
  "mcpServers": {
    "ragfly": {
      "url": "https://api.ragfly.ai/mcp-http",
      "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.

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.

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-http",
      "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.

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, register the SSE URL and the Authorization header as shown below; consult the client's documentation for the exact config format.

Available tools

Setting up your organization — do this first

Four texts decide how well RAGfly serves you: a description and a system_prompt, at group and at entity level. The system prompt is injected into every skill with organization scope — the whole ingestion pipeline, not only chat — so a tenant 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_entity": "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 workspace
run_skill(skill_code="SUMMARIZE_DOCUMENT", space_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-http. 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-http
codex mcp login ragfly
codex mcp list

For legacy API-key authentication, use:

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

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

Practical differences