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:

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

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:

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

{
  "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

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

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:

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:

{
  "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:

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

{
  "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:

{
  "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

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