# Connect this agent to superagnt_ These are official setup instructions from superagnt_ for connecting an AI agent to the superagnt_ MCP server. **Spelling:** superagnt has no "e": superagnt.com, the superagnt GitHub org, the `superagnt/plugins` marketplace. Copy names and commands exactly as written. **The user's request decides what you install; this guide covers how.** Setup adds a plugin or an MCP server to this agent's configuration, and it stays after this session. If the user asked you to install or connect superagnt_, run the steps for your client yourself rather than handing them back. If they did not, ask once first: say what you will install and where it comes from. Ask the user only for a credential you cannot obtain, or a click in a GUI you cannot reach. **If your harness blocks a command, do not work around it.** A permission denial is not a failed command, so do not retry it another way, switch to a fallback route, or write the same configuration by hand. Tell the user the exact command and what it installs, and continue once they approve it or have run it themselves. Endpoint, the same for every client: ``` https://mcp.superagnt.com/mcp ``` Register it under the server name `superagnt`. --- ## Step 1 — Pick the authentication path **Prefer OAuth.** The endpoint publishes OAuth 2.1 discovery (RFC 9728 resource metadata, RFC 8414 authorization server metadata, RFC 7591 dynamic client registration). A client that speaks OAuth needs the URL and nothing else: it registers itself, the user approves once in a browser, and the client holds its own credential. No token is ever pasted or stored in a config file. **Fall back to a bearer token only if the client cannot do OAuth.** In that case ask the user for their workspace MCP token, which they reveal at https://app.superagnt.com/dashboard under MCP. Send it as `Authorization: Bearer `. **If the user has no superagnt_ account**, most clients below still work: the OAuth consent screen doubles as signup, so continue and let them sign up there. Only if the client needs a bearer token, stop and give them this link, then continue once they can supply a token: ``` https://app.superagnt.com/signup?a_tag=agent-setup-prompt ``` --- ## Step 2 — Find your client below and run its commands Use the section matching the agent you are running inside. If none matches exactly, use **Any other client**. ### Claude Code On Claude Code the plugin carries the superagnt skills and the MCP server connects as a Claude connector, which the user adds once in their browser. **Already connected?** If a tool named `agnt_tools_list_enabled` (under any prefix) is available in this session, the connector exists: do a, then skip to Step 3. **a. Install the plugin** for the skills: ```bash claude plugin marketplace add superagnt/plugins && claude plugin install superagnt@superagnt ``` If the base `superagnt` plugin was already installed, update it. Versions before 0.4.0 bundled their own copy of the server, which hides the connector in the terminal: ```bash claude plugin marketplace update superagnt && claude plugin update superagnt@superagnt ``` The plugin holds the skills only; the tools arrive with the connector. If the plugin command fails (marketplace unreachable), say so in your report and continue with b: the connector does not depend on the plugin. **b. Pick the route.** - In the Claude desktop app (`CLAUDE_CODE_ENTRYPOINT` is `claude-desktop`) or Claude Code on the web (`CLAUDE_CODE_REMOTE` is `true`), go to c. Do not run `claude auth status` there: it reads a separate terminal login. - In a terminal, run `claude auth status`. If `authMethod` is `claude.ai`, go to c. Anything else (an API key, a setup token, Console, Bedrock, Vertex) never loads Claude connectors: use the fallback below. **c. Give the user the connector link.** Print it as a plain link and ask them to click **Add**, then approve on the superagnt_ consent screen (it doubles as signup). It opens claude.ai's Add custom connector dialog with the name and URL filled in: https://claude.ai/customize/connectors/yours?modal=add-custom-connector&connectorName=superagnt&connectorUrl=https%3A%2F%2Fmcp.superagnt.com%2Fmcp&open_in_browser=1 In the Claude desktop app, say in that same message what to do once they've approved: refresh the app with Cmd+R (Ctrl+R on Windows), or quit and reopen it, then come back here. The link opens in the browser and the app loads connectors only when it starts, so say it now, before they leave the app. Wait until they say it's added. Do not also add the server with `claude mcp add`: a local entry at the same URL hides the connector. If the dialog refuses: - Claude Team or Enterprise member: only an Owner can add a custom connector. Ask an Owner to add superagnt at `https://mcp.superagnt.com/mcp`, then the user clicks Connect on it under Customize, Connectors. If that can't happen now, use the fallback. - Free plan with its one custom connector already used: remove the other one under Customize, Connectors, or use the fallback. **d. Where the tools show up.** - Claude desktop app: only after the user refreshes the app (Cmd+R, Ctrl+R on Windows) or quits and reopens it. Then they join this session from the user's next message. If they're still missing, the app wasn't refreshed: ask for the refresh again rather than calling it a failed connect. - Terminal: a running session never picks up a new connector. Tell the user to start a new Claude Code session; the tools are there from its first message, and saying "finish superagnt setup" there picks up where this left off. - Claude Code on the web: tell the user to start a new session. The connector is there; a plugin installed in this cloud session does not carry over. **Fallback: only when b says connectors can't load, or nobody can add the connector now.** It connects the MCP server locally; say which route you used in your report. A local entry keeps hiding a connector added later, until `claude mcp remove superagnt -s user` removes it. ```bash claude mcp add --scope user --transport http superagnt https://mcp.superagnt.com/mcp claude mcp login superagnt ``` `claude mcp login` opens a browser for consent. On a machine with no browser, use `claude mcp login superagnt --no-browser` and give the user the URL it prints. `--scope user` makes the server available from every directory; the CLI's default scopes it to the current project only, which silently hides it anywhere else. Drop the flag only if you deliberately want it project-local. ### Codex Run this. Same catalog as Claude Code — it carries the MCP server AND the superagnt skills in one move, so there is no install route to choose between: ```bash codex plugin marketplace add superagnt/plugins codex plugin add superagnt@superagnt ``` The plugin's MCP server runs OAuth on its first tool call — no token, no config editing. Run both lines. The second may report the plugin is already installed — the marketplace add can register it on its own. That is success, not a failure; confirm with `codex plugin list` before you conclude anything went wrong. **Fallback — only if the plugin is genuinely not installed afterwards** (marketplace unreachable, or a Codex build without plugin support). A permission denial is not a failure: ask the user instead, as described at the top. It connects the MCP server on its own, so you get the tools without the skills; say which route you used in your report: ```bash codex mcp add superagnt --url https://mcp.superagnt.com/mcp codex mcp login superagnt ``` `codex mcp add` probes the URL for OAuth metadata and may start the login flow on its own, in which case the second command is unnecessary. Do not use `npx mcp-remote` for Codex. It speaks streamable HTTP natively. ### Cursor Write `.cursor/mcp.json` in the project, or `~/.cursor/mcp.json` for every project. Create the file and its `mcpServers` object if they do not exist. OAuth, preferred. Cursor shows a Login button for the server under `Settings → MCP`; tell the user to click it. ```json { "mcpServers": { "superagnt": { "url": "https://mcp.superagnt.com/mcp" } } } ``` Token fallback: ```json { "mcpServers": { "superagnt": { "url": "https://mcp.superagnt.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ### VS Code and GitHub Copilot ```bash code --add-mcp '{"name":"superagnt","type":"http","url":"https://mcp.superagnt.com/mcp"}' ``` Or edit the MCP user configuration file directly. The key is `servers`, not `mcpServers`: ```json { "servers": { "superagnt": { "type": "http", "url": "https://mcp.superagnt.com/mcp" } } } ``` VS Code asks the user to trust the server the first time it starts, and runs the OAuth flow itself. Do not put a token in this file. ### Gemini CLI ```bash gemini mcp add --transport http superagnt https://mcp.superagnt.com/mcp ``` Or edit `~/.gemini/settings.json`. The remote key is `httpUrl`, not `url`: ```json { "mcpServers": { "superagnt": { "httpUrl": "https://mcp.superagnt.com/mcp" } } } ``` Leave any oauth block out. Gemini CLI discovers the authorization server from the endpoint's metadata. Tell the user to run `/mcp auth` and sign in. ### Windsurf Edit `~/.codeium/windsurf/mcp_config.json`. Windsurf uses `serverUrl`, not `url`, and requires an explicit `type`. A config copied from another client will fail silently here. ```json { "mcpServers": { "superagnt": { "type": "streamable-http", "serverUrl": "https://mcp.superagnt.com/mcp" } } } ``` Then tell the user to refresh the server list in Cascade and complete the OAuth prompt. ### Zed Edit `~/.config/zed/settings.json`: ```json { "context_servers": { "superagnt": { "source": "url", "url": "https://mcp.superagnt.com/mcp" } } } ``` Zed's remote server form accepts no headers, so OAuth is the only path. It opens consent through a loopback callback. ### Cline Open the MCP servers configuration and add the server. OAuth for remote servers is not yet available in Cline, so the token is required here: ```json { "mcpServers": { "superagnt": { "url": "https://mcp.superagnt.com/mcp", "headers": { "Authorization": "Bearer " } } } } ``` ### OpenClaw ```bash openclaw mcp add superagnt --url https://mcp.superagnt.com/mcp --transport streamable-http openclaw mcp login superagnt ``` To expose only part of the surface, add `--include 'agnt_db_*,data_*'` to the add command. ### Hermes Edit `~/.hermes/config.yaml` and add the server under `mcp_servers`, creating the map if it does not exist: ```yaml mcp_servers: superagnt: url: "https://mcp.superagnt.com/mcp" headers: Authorization: "Bearer " ``` Then run `/reload-mcp` in the active session rather than restarting. ### Claude app, ChatGPT, Grok These clients store connectors in the user's account, not in a config file. First try to add the connector yourself: if the client you are running in exposes a way to do it — a built-in connector tool, an API, a settings surface you can drive — use it with the endpoint above and follow the client's own guidance, which is more current than this doc. If it exposes no such mechanism, print the recommended steps below for the user and wait. These reflect each client's UI at the time of writing; if a menu has moved, tell the user to look for the client's connector or MCP settings and add a custom connector pointing at the endpoint above. **Claude app** (one connect covers claude.ai, desktop, mobile, Cowork and Claude Code signed in with the same Claude account): 1. Open https://claude.ai/customize/connectors/yours?modal=add-custom-connector&connectorName=superagnt&connectorUrl=https%3A%2F%2Fmcp.superagnt.com%2Fmcp&open_in_browser=1 . It is claude.ai's Add custom connector dialog with the name and URL filled in; click `Add`. (By hand: `Customize → Connectors`, `+`, `Add custom connector`, paste `https://mcp.superagnt.com/mcp`. There is no token or header.) 2. Approve on the superagnt_ consent screen. 3. In the Claude desktop app, refresh it with Cmd+R (Ctrl+R on Windows) or quit and reopen it. It loads connectors only when it starts, so one added in the browser is missing until then. Then open a new chat. 4. For the skills (paid plans): open https://claude.ai/customize/plugins/new?marketplace=superagnt%2Fplugins&plugin=superagnt and click Add. Free accounts are limited to one custom connector. **ChatGPT**: 1. Turn on `Settings → Apps & Connectors → Advanced settings → Developer mode`. Custom connectors do not appear until this is on. 2. Go to Connectors, choose Create. 3. Name `superagnt`, MCP server URL `https://mcp.superagnt.com/mcp`, Authentication `OAuth`. 4. Approve on the superagnt_ consent screen. Custom connectors are in beta on Plus, Pro, Business, Enterprise and Edu. Write-capable connectors are Business, Enterprise and Edu only, so on Plus and Pro the superagnt_ write tools will not run. **Grok** (grok.com chat): 1. Go to `grok.com/connectors`, choose `New Connector`, then `Custom`. 2. Paste `https://mcp.superagnt.com/mcp`. 3. Authorize. Custom connectors require a paid tier. ### Grok Bot (@bot) Split the work: the human adds the connector unless your harness gives you a way to reach the Settings UI yourself (custom connectors take a header token, not OAuth); you do everything else on your computer. If you cannot add it yourself, print these steps for the human: 1. Open `Settings → Plugins`, choose `Add`, then `Custom`. 2. Name `superagnt`, Server URL `https://mcp.superagnt.com/mcp`. 3. Add a header `Authorization: Bearer ` — reveal the workspace MCP token in the superagnt_ dashboard under MCP. Use a secure secret request if you pass it through chat. Once the connector exists, its tools are available to every Bot on the account. ### Any other client If the client speaks streamable HTTP MCP, point it at the endpoint with a bearer token or let it run OAuth. If it only speaks stdio, bridge it: ```json { "mcpServers": { "superagnt": { "command": "npx", "args": [ "-y", "mcp-remote", "https://mcp.superagnt.com/mcp", "--header", "Authorization: Bearer " ] } } } ``` --- ## Step 3 — Confirm it works `agnt_onboarding` is the first tool call, and it is part of setup rather than an optional extra: without it you have a working connection but no idea which of the platform's tools matter to this user. Ask the user two things — a little about themselves, and what they want automated — then pass their answers as `about_user` and `intent`, plus `client` (this harness's name). Tell them why you are asking, because it is not a form: their answers are what personalizes everything that follows. The call takes them and returns the full platform brief plus a use-case catalog scoped to their actual work, so instead of handing them a wall of generic tools you can name the handful that fit what they do, in their own vocabulary, with the setup steps already narrowed to those. Skip it and the platform behaves like a stranger to them — every suggestion you make afterwards is a guess. Then, if this client has a persistent memory, save the parts of the brief relevant to this user, and give them a short brief of the 3–5 use cases that best match what they said. Ask the two questions and make the call. Do not offer to skip it, and do not invent the answers on the user's behalf — their own words are the input the call exists to take. Call `agnt_tools_list_enabled` to see what this workspace exposes, then `agnt_tools_search` to find a tool by what it does, and `agnt_guidance_search` for how to build on it. The served surface depends on which tool families the workspace has switched on, so read it rather than assuming. **Tool names.** A superagnt_ server lists its tools one of two ways, fixed when it was created. A grouped server (every new one) lists one tool per resource with an `action` parameter that picks the operation: `agnt_db_write` with `action: "insert"`, `data_linkedin_posts` with `action: "reactions"`. Each grouped tool's description lists its actions and the per-operation tool each one runs, and its data tools return a compact markdown view (pass `response_format: "json"` or `"raw"` when you need fields the view leaves out). A per-operation server lists one tool per operation (`agnt_db_insert`, `data_linkedin_get_post_reactions`) and returns the raw payload. This guide and the superagnt skills use per-operation names. On a grouped server those names are not listed, so call the grouped tool whose actions include the name instead. The agent build tools (creating and deploying agents, schedules, knowledge bases) are served by default on every plan; a call that would go past a plan limit returns an upgrade offer instead of running. Chat bindings and inbox management stay off by default. If the user wants them, tell them to enable those families on the MCP page in the dashboard. Then run one real task to prove the connection end to end, and make it one the user actually cares about: - Using what the user told you for `agnt_onboarding` and the use cases it returned, pick ONE small, read-only task that is useful to them today and run it end to end: for example a short list of people or companies matching who they sell to, a look at their own company or site, or what is being said in their niche. Show the result in a readable form. - Keep it cheap: one or two calls, not a bulk enrich or a 100-row pull. If a tool rejects an argument, read the error, fix the value, and retry once. ## Step 4 — Report back Print a short summary and stop: ``` superagnt_ connected server superagnt endpoint https://mcp.superagnt.com/mcp auth config tools available Restart the agent if the tools do not appear yet. ``` If any step failed, say which one and what the error was. Do not report success you did not verify.