# Connecting agents over MCP

Every tool and skill your organization serves is available through one MCP
endpoint. People connect with their own account; CI, scripts and bots connect
with a service account key. Either way, groups decide which tools each caller
sees.

## Connect as yourself

Add this URL as a remote MCP server (streamable HTTP) in your agent:

```text
https://api.zenitya.com/mcp
```

Your agent opens a browser: sign in with Google, choose the organization and
approve access. You get the tools and skills granted to the Default group and
to every group you belong to. There is no key to copy.

### Claude Code

```sh
claude mcp add --transport http --scope user \
  zenitya https://api.zenitya.com/mcp
```

Then run `/mcp` in Claude Code, choose **zenitya** and sign in in the browser
(or run `claude mcp login zenitya` from a shell). `--scope user` makes Zenitya
available in every project; leave it out to add it to the current project only.

### Claude

In Claude on the web or desktop, open **Customize**, then **Connectors**, then
**Add** and **Add custom connector**. Name it Zenitya, enter
`https://api.zenitya.com/mcp`, keep the detected sign-in settings and click
**Add**. Turn it on in a conversation from the **+** menu, under
**Connectors**.

On Team and Enterprise plans, an owner adds the connector once in
**Organization settings**, **Connectors**; members then click **Connect** on it
under **Customize**, **Connectors**.

### Codex

With the Codex CLI:

```sh
codex mcp add zenitya --url https://api.zenitya.com/mcp
codex mcp login zenitya
```

`codex mcp login` opens the browser to sign in; add `--no-browser` on a remote
machine and paste the redirect URL back. `codex mcp list`, or `/mcp` in a
session, shows the connected servers.

In the ChatGPT desktop app, open **Settings**, **MCP servers**, **Add server**.
In the Codex IDE extension, open the gear menu, **MCP servers**, **Add server**.
Name it `zenitya`, choose **Streamable HTTP**, enter the URL, save and restart,
then select **Authenticate** to sign in.

### Cursor

Add Zenitya to `~/.cursor/mcp.json` (every project) or `.cursor/mcp.json` (one
project):

```json
{
  "mcpServers": {
    "zenitya": {
      "url": "https://api.zenitya.com/mcp"
    }
  }
}
```

Cursor signs in with OAuth when it first connects; you can sign in and out of
the server from Cursor's MCP settings.

### Pi

```sh
pi mcp add zenitya --url https://api.zenitya.com/mcp
pi mcp login zenitya
```

`pi mcp list` checks the connection. Inside a session, `/mcp` shows Zenitya and
offers to sign in when it needs to.

## What agents see

- Your tools as `<project>.<tool>`, for example `orders.findLateOrders`, with
  their descriptions, input and output schemas and hints.
- Tools of connected MCP servers as `<server>.<tool>`, for example
  `linear.list_issues`.
- `list_skills` and `load_skill`, when you are granted at least one
  [skill](skills.md). The server asks agents to check skills at the start of
  every task. Connected MCP servers add their own skills; see
  [Skills from connected MCP servers](skills.md#skills-from-connected-mcp-servers).

A deploy changes what agents see on their next request; there is nothing to
reconnect.

## Connect with a service account key

For automation, an owner or admin creates a service account in the Zenitya
app, adds it to groups, and creates a key with the `invoke` scope. Keys are
shown once. Use the organization's endpoint, with the organization ID from
`zya whoami --json | jq -r .organizationId` or the app's settings, and send the
key in the `x-api-key` header:

```text
https://api.zenitya.com/api/v1/organizations/<org-id>/mcp
```

Keep the key in an environment variable, `ZENITYA_API_KEY` below, and let the
agent read it. Never write the key itself into a config file.

### Claude Code

In the project's `.mcp.json`:

```json
{
  "mcpServers": {
    "zenitya": {
      "type": "http",
      "url": "https://api.zenitya.com/api/v1/organizations/<org-id>/mcp",
      "headers": { "x-api-key": "${ZENITYA_API_KEY}" }
    }
  }
}
```

### Codex

In `~/.codex/config.toml`; `env_http_headers` maps a header to the name of the
variable that holds its value:

```toml
[mcp_servers.zenitya]
url = "https://api.zenitya.com/api/v1/organizations/<org-id>/mcp"

[mcp_servers.zenitya.env_http_headers]
x-api-key = "ZENITYA_API_KEY"
```

### Cursor

In `~/.cursor/mcp.json` or `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "zenitya": {
      "url": "https://api.zenitya.com/api/v1/organizations/<org-id>/mcp",
      "headers": { "x-api-key": "${env:ZENITYA_API_KEY}" }
    }
  }
}
```

### Pi

In `~/.pi/agent/mcp.json` or `.pi/mcp.json`:

```json
{
  "mcpServers": {
    "zenitya": {
      "url": "https://api.zenitya.com/api/v1/organizations/<org-id>/mcp",
      "headers": { "x-api-key": "${ZENITYA_API_KEY}" }
    }
  }
}
```

Restart the agent after changing the environment it starts with.

## Troubleshooting

| Response | Meaning                                                             |
| -------- | ------------------------------------------------------------------- |
| HTTP 401 | The key is missing, mistyped, expired or revoked                    |
| HTTP 403 | The key lacks the `invoke` scope, or the account has no beta access |
| HTTP 404 | The organization ID is wrong, or the key belongs to another one     |
| No tools | Nothing is granted to the caller's groups, or nothing is deployed   |

A tool's own failure comes back as a tool error with its message, so the agent
can read it and correct its input.