> For the complete documentation index, see [llms.txt](https://docs.kinesis.network/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.kinesis.network/mcp/connect.md).
# Connect an MCP client
Choose your app, connect to Kinesis, and tune the tools it can discover.
Choose your app for copyable setup instructions. Use OAuth to sign in with your Kinesis account; use an API key for automation that cannot open a browser.
Kinesis directory submissions for Claude, ChatGPT and Cursor are awaiting approval. These manual setups are available now.
## Before you connect
You need a [Kinesis account](https://portal.kinesis.network/signup) and membership in the organization you want to use. On the consent screen, review permissions and choose which organizations the connection may reach. Actions follow your role in each organization.
API keys are created in [Account settings → API keys](https://portal.kinesis.network/dashboard/account). Choose the scopes, expiry and organization or project limits your integration needs. If an organization requires SSO, complete its [SSO sign-in](/organizations/single-sign-on.md) before approving a connection or creating a key that can reach it.
## Connection options
The same URL options work across clients. Append the first option with `?` and additional options with `&`; quote the full URL in shell commands.
| Option | Effect |
| ----------------------- | ---------------------------------------------- |
| `?mode=all` | Expose one tool per action |
| `?readonly=true` | Expose only read tools |
| `?groups=apps,projects` | Load only the named groups, plus built-in docs |
For a focused read-only connection that can also identify you and your organizations:
```
https://mcp.kinesis.network/mcp?mode=all&groups=account,projects,apps&readonly=true
```
The Claude Code and Codex quickstarts use individual actions; Cursor uses the smaller default compact catalog. Both modes are supported. Choose the setup that fits your client, then narrow it if needed. Filters change tool discovery; they do not grant extra scopes or resource access.
## Choose a catalog mode
**Compact is the default.** Without filters, it exposes 18 tools. Reads and changes are separated so clients can distinguish inspection from mutation.
| Resource group | Read tool | Write tool |
| -------------- | ---------- | ---------------- |
| Account | `account` | `account_write` |
| Projects | `projects` | `projects_write` |
| Apps | `apps` | `apps_write` |
| Sharing | `sharing` | `sharing_write` |
| Grids | `grids` | `grids_write` |
| Servers | `servers` | `servers_write` |
| Catalog | `catalog` | None |
| Billing | `billing` | `billing_write` |
These tools run named actions with `{action, params}`. The three remaining tools are `browse_github`, `read_docs` and `describe_action`.
To check your identity, call tool `account` with:
```json
{"action": "whoami", "params": {}}
```
To get an action's complete argument schema, call `describe_action`:
```json
{"action": "create_app"}
```
It returns `action`, `tool`, `title`, `description`, `inputSchema` and `annotations`. For `create_app`, `tool` is `apps_write`; for `get_app_status`, it is `apps`. Use it before constructing complex inputs such as `create_app` or `update_app`. It describes actions in the selected folded groups and is present only when at least one such group is loaded. It does not execute the action.
For a client or integration that calls individual action names, connect with:
```
https://mcp.kinesis.network/mcp?mode=all
```
This exposes 95 tools, including `whoami` and `create_app` directly. Pass their arguments without an `action`/`params` wrapper. `browse_github` and `read_docs` are direct calls in both modes; `describe_action` is a compact-mode helper.
Both modes enforce the same action schemas and permissions. Compact descriptions omit pagination and idempotency fields from short signatures; those arguments remain supported. Some advertised schemas shorten nested configuration, and compact direct-tool schemas omit validation-only constraints. `describe_action` and the [reference](/mcp/tools.md) provide complete schemas; calls still enforce the full validation rules.
## OpenAI profile
Use `https://mcp.kinesis.network/mcp?profile=openai` for 94 individual action tools with credential restrictions and top-level output schemas. It omits `get_byod_token` and `describe_action`; it cannot be combined with `mode=compact`. Group and read-only filters still apply. Read the [OpenAI profile guide](/mcp/openai-profile.md) before using its inputs.
## Load selected groups
```
https://mcp.kinesis.network/mcp?groups=account,projects,apps
```
For inspection without write actions:
```
https://mcp.kinesis.network/mcp?groups=account,projects,apps&readonly=true
```
| Group | Includes |
| ---------- | ----------------------------------------------------------------------------------------------- |
| `account` | Identity, organizations, settings, audit, received organization invitations and notifications |
| `projects` | Project listing, creation, name/visibility updates and deletion |
| `apps` | Apps, templates, placement, moves, lifecycle, logs, usage, builds, rollback and domains |
| `github` | Connected accounts and repository browsing, including file contents |
| `sharing` | Members, roles, ownership, organization invitations, grantees and existing resource invitations |
| `grids` | Grid composition, server priority and grid app controls |
| `servers` | Orders, server details/logs, BYOD tokens, power, Smart Lifecycle and SSH keys |
| `catalog` | Provider catalog and marketplace |
| `billing` | Balance, costs, invoices, ledger, payment methods, vouchers and node protection |
| `docs` | Built-in guides; always included |
No filter loads all groups. `groups` accepts comma-separated values and repeated query parameters. `readonly=true` or `readonly=1` removes write actions before groups are folded. An unknown group or mode returns `400 invalid_request`.
Filters control discovery; scopes and resource access are enforced independently. `account` must be included explicitly when using a group filter that needs identity or notifications.
## Choose the organization
Call `account` with `{"action":"list_orgs","params":{}}`. For organization-level actions, put the returned slug inside `params.org`, for example `{"action":"list_members","params":{"org":"acme"}}` on `sharing`. Resource-ID actions resolve the organization themselves. `list_projects` and `list_apps` span organizations unless `org` filters them.
A role, credential scope and organization/project restriction must all permit the action. `org_required` lists slugs when a call needs one. Connections approved before `members:read`, `members:write`, `org:write` and `audit:read` existed need re-approval for those permissions.
## Verify the connection
1. In compact mode call `account` with `{"action":"whoami"}`. In all mode call `whoami` with `{}`.
2. Call `read_docs` with `{"topic":"getting_started"}`.
3. With `projects:read`, call `projects` with `{"action":"list_projects","params":{}}`, or `list_projects` in all mode.
If organization SSO blocks key creation or OAuth approval in the browser, complete [SSO](/organizations/single-sign-on.md) first. Existing keys and connections continue working under their permissions.
If an action fails with `insufficient_scope`, inspect `requiredScopes`. Changing the catalog mode or group filter does not grant permission.
## Built-in resources
The server advertises nine Markdown resources. Clients without a resource UI can call `read_docs` with the final path segment as `topic`.
| Resource | Topic |
| -------------------------------- | -------------------------------------------------------- |
| `kinesis://docs/getting_started` | First deployment |
| `kinesis://docs/deploy` | Sources and app configuration |
| `kinesis://docs/operate` | Lifecycle, logs, builds, rollback and domains |
| `kinesis://docs/troubleshoot` | Status and failure diagnosis |
| `kinesis://docs/servers` | Grids, dedicated servers and orders |
| `kinesis://docs/billing` | Credits, costs and payments |
| `kinesis://docs/organizations` | Organizations, members, roles, settings and audit |
| `kinesis://docs/sharing` | Adding organization members to resources and grid access |
| `kinesis://docs/errors` | Error codes and recovery |
The server is stateless and does not provide change-event subscriptions. Send one JSON-RPC message per HTTP request; batches are not supported.
## Troubleshooting
| Symptom | Check |
| -------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| `401` before tools load | Bearer header, key expiry/revocation or OAuth authorization |
| An individual name such as `create_app` is missing | Default compact mode uses `apps_write` with `action: "create_app"`; use `mode=all` for individual names |
| Missing write actions | Check the `_write` tool and the `readonly` filter |
| An action was sent to the wrong tool | Follow the error’s named tool, or read `describe_action(...).tool` |
| `add_credits` or `set_auto_reload` is missing | These actions are not available through MCP; billing belongs to organization admins |
| Missing resource family or identity | `groups` filter; include `account` for `whoami` |
| `403 insufficient_scope` | `requiredScopes` and the user's resource role |
| `invalid_request` on a compact call | Read `issues` under `params.*`; action-schema failures also include `inputSchema` |
| `404` | Use the MCP host and `/mcp` path above |
| A subscription request is refused | Use explicit reads with this stateless server |
| `429 rate_limited` | Honor `Retry-After` and reset headers |
Next: [Agent workflows](/mcp/workflows.md) and [Tool reference](/mcp/tools.md).
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://docs.kinesis.network/mcp/connect.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
Claude Code
Codex
Cursor
Custom agent