> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuphos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP

> Connect Claude Code, Codex, or any MCP client to the Nuphos Agent over the Model Context Protocol.

This connector points the other way: instead of giving Nuphos access to an
external system, it exposes the Nuphos Agent as a remote **MCP server**, so
MCP-capable coding agents — Claude Code, Codex, and others — can hand it
infrastructure work directly: provision servers and clusters, debug
deployments, or answer questions about your cloud accounts.

## Connect

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

```
https://api.nuphos.ai/mcp
```

### Claude Code

1. Register the server:

   ```bash theme={null}
   claude mcp add --transport http nuphos https://api.nuphos.ai/mcp
   ```

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`:

```toml theme={null}
[mcp_servers.nuphos]
url = "https://api.nuphos.ai/mcp"
```

Then run the OAuth flow from the terminal:

```bash theme={null}
codex mcp login nuphos
```

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:

```
Authorization: Bearer <your Nuphos token>
```

## In the Nuphos app

Conversations started over MCP are real [agent sessions](/agent/sessions) —
every one runs inside one of your teams and shows up in that team's workspace
like any other session, with its full transcript visible to the team.

## What your coding agent can do through it

The MCP server exposes these tools:

| Tool                        | What it does                                                                             |
| --------------------------- | ---------------------------------------------------------------------------------------- |
| `nuphos_list_teams`         | Your teams and their `team_id`s. Call this first.                                        |
| `nuphos_ask`                | Send a prompt to the agent. Requires `team_id`; blocks until the run finishes.           |
| `nuphos_check`              | Reconnect to a session — returns the answer, or `running` if the agent is still working. |
| `nuphos_list_credentials`   | Cloud credentials you can use in a team, and which are enabled for a session.            |
| `nuphos_update_credentials` | Replace the set of credentials a session may use.                                        |
| `nuphos_capabilities`       | What the Nuphos Agent can do.                                                            |

In practice: while Claude Code is building your app, it can ask Nuphos to
*"provision a Postgres on the staging cluster"* or *"why is the deploy
failing?"* — the Nuphos Agent does the infrastructure work with your connected
accounts and returns the answer to your coding agent.

### Sessions

Every conversation runs inside one of your teams — pass a `team_id` from
`nuphos_list_teams` to `nuphos_ask`.

Pass your own `session_id` to make a conversation 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 conversation with full
history.

## Permissions & authorization

MCP is an **entry point**, not an escape hatch — sessions started over MCP obey
the same boundaries as sessions 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](/security/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 session settings.
* **Scoping credentials per session.** A new session 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 session should keep — it is a full
  replacement, and it applies from the next `nuphos_ask` onward.
* **Soft boundary — what may run.** Changes still go through
  [plan approvals](/security/approvals), and
  [Auto-authorization](/security/auto-mode) still governs each command the
  Nuphos Agent runs — your standing rules apply identically to MCP-initiated
  sessions.

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