Connect Your Agent

There are two ways to connect. Claude Desktop, claude.ai and ChatGPT take a connector URL that you paste in. Claude Code, Cursor, Codex and VS Code take a config entry, which flydocs connect remote writes for you or you can write by hand. Every route ends in the same browser sign-in.

The portal shows the same instructions, filled in for your deployment, at Account → Connect your agent. That page also shows when an agent last used the connection and which client it was.

Before you start

• Sign in to the FlyDocs portal at least once with the account you will use. A connection from an account with no portal profile is refused until you do.
• You need to belong to a FlyDocs organization, and to a workspace in it.
• Remote MCP can be switched off for an organization by an admin. If calls are refused for that reason, see the org switch.

Claude Desktop, claude.ai and ChatGPT

These clients connect by URL. There is nothing to install.

1. Open the client's connector settings and choose to add a custom connector. In Claude Desktop and claude.ai that is Settings → Connectors → Add custom connector. The label varies between versions. You are looking for the option that takes a remote MCP server URL. In ChatGPT, add it as a custom connector the same way; the menu names differ by plan and version.
2. Paste the connector URL.
3. The client opens a FlyDocs sign-in. Sign in with your portal account and approve the consent screen. It asks for one permission, mcp:tools, which is the only one the server uses.

https://mcp.flydocs.ai/mcp

The server publishes standard OAuth discovery metadata, so there is no client ID, secret or redirect to enter. Claude identifies itself with a client ID metadata document, a URL it hosts, so connecting creates no OAuth application on the FlyDocs side. Dynamic client registration is off. A client that cannot identify itself this way will not connect today.

Claude Code, Cursor, Codex and VS Code: flydocs connect remote

With the FlyDocs CLI at 1.3.27 or later, one command registers the remote server with every supported agent it finds on the machine. Run it from any directory. It does not need a FlyDocs project.

flydocs connect remote                      # every agent it finds, with a preview
flydocs connect remote --client cursor      # one agent: claude, cursor, codex or vscode
flydocs connect remote --yes                # apply without the confirmation prompt
flydocs connect remote --json               # machine-readable result, never prompts

It asks the server for the connector URL, the OAuth client and the server name (flydocs-cloud), shows what it will change in each agent, and waits for your yes. Nothing is written without it unless you pass --yes. Only the flydocs-cloud entry is touched. Your other servers, and the local flydocs server, are left alone. A config file it cannot parse is reported and not overwritten.

It writes to these places:

Without --client, the command detects agents by their config directories, or by claude --version answering for Claude Code. If it finds none, it says so and writes nothing. Pass --client to name one.

Manual configuration

The same entries, written by hand. The server name is flydocs-cloud so it never collides with the local flydocs server.

Claude Code

claude mcp add --transport http --scope user \
  --client-id <client-id> --callback-port <port> \
  flydocs-cloud https://mcp.flydocs.ai/mcp

The client ID and callback port are public values that the server publishes. Read them from https://mcp.flydocs.ai/mcp/install-config, or copy the finished command from Account → Connect your agent. Then run /mcp in Claude Code and choose Authenticate. Claude Code needs a version that supports --client-id and --callback-port.

Cursor

{
  "mcpServers": {
    "flydocs-cloud": { "url": "https://mcp.flydocs.ai/mcp" }
  }
}

Cursor signs in with its own client identity, so no client ID is needed.

VS Code

Run MCP: Open User Configuration and add the entry. VS Code uses a servers key, not mcpServers.

{
  "servers": {
    "flydocs-cloud": { "type": "http", "url": "https://mcp.flydocs.ai/mcp" }
  }
}

If VS Code asks for a client ID when you sign in, use the clientId from the install config.

Codex

[mcp_servers.flydocs-cloud]
url = "https://mcp.flydocs.ai/mcp"

Then run codex mcp login flydocs-cloud. If Codex asks for a client ID, use the clientId from the install config.

Signing in

Sign-in is OAuth through your FlyDocs account. The client opens your browser, you approve the consent screen, and the client holds the token. FlyDocs stores no password for it and there is no API key to rotate. Run /mcp (Claude Code), the server list (Cursor, VS Code) or codex mcp login to sign in again at any time.

Organizations and workspaces

One connection covers every organization you belong to. Calls run in your primary organization: the Default Organization you set in account Preferences, else the organization of your Default Workspace, else the only one you are in. To act in another, name it. The agent passes organization on the call, with no reconnect.

Each call also acts on one workspace. If you can reach exactly one in the organization, it is chosen for you. If you can reach several, the first call comes back with the workspace slugs and asks you to pick. The agent then passes workspace on every later call. Asking "what do I have access to in FlyDocs?" makes the agent call flydocs_whoami, which lists all of it.

Disconnecting

flydocs disconnect remote                    # remove from every agent that has it
flydocs disconnect remote --client codex     # one agent
flydocs disconnect remote --yes              # no confirmation

This removes the flydocs-cloud entry and nothing else. It works even if the FlyDocs server cannot be reached. Restart the agent afterwards to drop the server. For Claude Desktop, claude.ai and ChatGPT, remove the connector in the client's connector settings.

To cut off one person's access from the FlyDocs side, remove them from the organization. To close Remote MCP for everyone in an organization, an admin uses the org switch.

To check what is registered on a machine, run flydocs doctor --tools. It reports each detected agent under mcp.remote.registration.* and never needs the network for it. See Tool Surface Setup.