> 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

Connect over HTTP with OAuth or an API key, then verify the available tools.

The Kinesis MCP server exposes project, app, compute and billing operations to compatible agents. Connect to:

```
https://mcp.kinesis.network/mcp
```

Use a client that supports remote MCP over HTTP. The exact configuration file and field names depend on your client; the connection values below are the same across clients.

| Setting        | Value                                            |
| -------------- | ------------------------------------------------ |
| Name           | `kinesis`                                        |
| Transport      | Remote HTTP / Streamable HTTP                    |
| Server URL     | `https://mcp.kinesis.network/mcp`                |
| Authentication | OAuth, or an API key in the Authorization header |

{% tabs %}
{% tab title="OAuth" %}

1. Add the server URL to your client's remote MCP connections.
2. Start the client's authorization flow. It discovers Kinesis authorization metadata from the server's challenge.
3. Sign in to Kinesis and review the requested permissions in the browser.
4. Return to the client, refresh its tools and call `whoami` to confirm the account and granted scopes.

Use this path when your client supports MCP OAuth. Access is tied to the connection the user authorizes. The client handles token refresh when offline access is granted.
{% endtab %}

{% tab title="API key" %}

1. Create a key in [Kinesis Settings](https://portal.kinesis.network/dashboard/settings). If API keys are not visible, contact support for access.
2. Set the server URL and configure this HTTP header using your client's secret or environment-variable mechanism:

```http
Authorization: Bearer kn_your_api_key
```

3. Refresh the tool list and call `whoami`.

Use an API key's scopes, project restrictions and expiry to match the integration. A key with `apps:read` and `monitoring:read` can inspect permitted apps and logs, but cannot deploy them. Add the relevant project scopes when listing projects is needed.
{% endtab %}
{% endtabs %}

## Start with a focused tool set

Pass `groups` in the connection URL to expose only the groups you need:

```
https://mcp.kinesis.network/mcp?groups=account,projects,apps
```

For inspection without write tools:

```
https://mcp.kinesis.network/mcp?groups=account,projects,apps&readonly=true
```

| Group      | Includes                                                 |
| ---------- | -------------------------------------------------------- |
| `account`  | Identity and credential context                          |
| `projects` | Project listing, creation, renaming and deletion         |
| `apps`     | Apps, templates, status, logs, usage, builds and domains |
| `github`   | Connected GitHub accounts and repository browsing        |
| `grids`    | Grid listing and composition                             |
| `servers`  | Provisioning, power, replacement and order management    |
| `catalog`  | Provider catalog and marketplace browsing                |
| `billing`  | Balance, costs, auto-reload and hosted payment links     |
| `docs`     | Built-in platform guide; always included                 |

With no group filter, all groups are available. `readonly=true` removes write tools. These options control tool discovery for that connection; credential scopes and resource access are still enforced independently. An unknown group returns `invalid_request`.

## Verify the connection

Ask your client to call `whoami`, then `read_docs` with `topic: "getting_started"`. List the projects only if the connection has `projects:read`.

If `whoami` is missing, include `account` in `groups`. If a tool call fails with `insufficient_scope`, inspect `requiredScopes`; changing the group filter does not grant that permission.

## Protocol and resources

The server advertises tools and seven Markdown resources:

| Resource                         | Topic                                      |
| -------------------------------- | ------------------------------------------ |
| `kinesis://docs/getting_started` | Projects, apps and the first deployment    |
| `kinesis://docs/deploy`          | Images, repositories and app configuration |
| `kinesis://docs/operate`         | Lifecycle, logs, builds and domains        |
| `kinesis://docs/troubleshoot`    | Status interpretation and common failures  |
| `kinesis://docs/servers`         | Grids, dedicated servers and orders        |
| `kinesis://docs/billing`         | Credits, costs and payment behavior        |
| `kinesis://docs/errors`          | Error codes and recovery                   |

Clients that do not expose resources can call `read_docs` with the final path segment as `topic`.

The implementation is stateless and does not provide change-event subscriptions. Use one JSON-RPC message per HTTP request; batches are not supported. Authentication, body limits and rate limits apply before a tool runs.

## Connection troubleshooting

| Symptom                                  | Check                                                             |
| ---------------------------------------- | ----------------------------------------------------------------- |
| `401` before tools load                  | Bearer header, API-key expiry/revocation, or the OAuth login flow |
| `403 insufficient_scope`                 | Required permission and the account's resource role               |
| Missing write tools                      | Whether `readonly=true` is set                                    |
| Missing resource family                  | The `groups` filter                                               |
| `404` at the server URL                  | Use the MCP host and `/mcp` path shown above                      |
| A listen/subscription request is refused | Expected for this stateless server; use explicit reads            |
| `429 rate_limited`                       | Honor `Retry-After` and reset headers before retrying             |

Next: [Agent workflows](/mcp/workflows.md) and the [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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.kinesis.network/mcp/connect.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.