Skip to main content
The remote Nuphos MCP server lets an MCP client hand work to your team’s agents: provision servers and clusters, debug deployments, or answer questions about cloud accounts. It is a tool interface into Nuphos, not the boundary that determines which runtimes Nuphos can run. This is different from a hosted runtime. With a hosted runtime, Nuphos runs your Claude Code account on a workspace-isolated computer through OpenAB while preserving Claude Code’s native harness. With this connector, an MCP client calls Nuphos remotely and an agent on the workspace’s configured runtime handles the work.

​
Connect

The server speaks MCP Streamable HTTP (JSON responses) at:

​
Claude Code

  1. Register the server:
  2. Open Claude Code. The server is listed as Authorization needed — it can’t call tools yet.
  3. Run /mcp, select nuphos, and choose Authenticate. Your browser opens the Nuphos authorization page.
  4. If you are already signed in to nuphos.ai, it’s a single Authorize click; otherwise sign in with your email and a verification code. Back in Claude Code, the server shows as connected.
Tokens refresh automatically after that — you won’t be asked again.

​
Codex

Add the server to ~/.codex/config.toml:
Then run the OAuth flow from the terminal:
Your browser opens the same Nuphos authorization page as above.

​
Other MCP clients

Any client that supports Streamable HTTP with OAuth 2.1 discovery works the same way. Clients without OAuth support can send a Nuphos token directly:

​
In the Nuphos app

Work started over MCP runs as real agents. Each one belongs to a team, runs on that team’s connected runtime, and shows up in the workspace subject to the conversation’s access controls.

​
What an external agent can do through it

The MCP server exposes these tools: In practice: while Codex is building your app, it can ask Nuphos to “provision a Postgres on the staging cluster” or “why is the deploy failing?”. Nuphos starts or resumes a shared agent, runs it on the team’s runtime with the allowed accounts, and returns the result to Codex.

​
Agents

Every agent runs inside one of your teams — pass a team_id from nuphos_list_teams to nuphos_ask. Pass your own session_id to make an agent resumable: if nuphos_ask times out on the client side, the agent keeps running — reconnect with nuphos_check using the same session_id to fetch the result. Reusing the session_id on a later nuphos_ask continues the same agent with full history.

​
Permissions & authorization

MCP is an entry point, not an escape hatch — agents started over MCP obey the same boundaries as agents started in the app:
  • Hard boundary — who is acting. The OAuth flow authenticates you, so every MCP call acts as your Nuphos user with your access control: your team role and the member allow-lists on each account. Access is enforced server-side on every request — the agent can never use a credential your user isn’t allowed to use, regardless of agent settings.
  • Scoping credentials per agent. A new agent may use all credentials you can access in that team. To narrow what the agent can touch, call nuphos_update_credentials with the exact set of ids (from nuphos_list_credentials) the agent should keep — it is a full replacement, and it applies from the next nuphos_ask onward.
  • Soft boundary — what may run. Significant cloud work uses plans; these are not a universal gate on every write, and the conversation’s permission mode applies to each command the agent runs, the same as in the app.

​
Good to know

  • nuphos_ask blocks until the run finishes — for long tasks, pass a session_id and poll with nuphos_check instead of relying on one long request.
  • Bearer-token auth (for clients without OAuth) carries exactly the same permissions as the OAuth flow — it’s your user either way.

​
Self-hosted endpoints and tokens

For a self-hosted backend, replace the hosted base URL with your backend’s public URL and configure the OAuth client against that deployment. Treat bearer tokens as credentials; use a securely configured client rather than putting a token in a prompt or repository. For clients without OAuth, obtain an authorized token through your deployment’s supported sign-in flow and review its scope.