> 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/custom-agent.md).

# Custom agent

Connect any compatible agent or MCP client using Streamable HTTP, OAuth or a scoped API key.

Use these settings for your own agent or any client that supports remote MCP over **Streamable HTTP**. Kinesis hosts the server; you do not need to run a local server process.

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

## Connect and authenticate

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

1. Add the URL above as a remote HTTP server in your client's MCP settings.
2. Start its sign-in or authorization flow. The client discovers Kinesis authorization metadata from the server's challenge.
3. Sign in to Kinesis, review permissions and select the organizations the connection may reach. Complete organization SSO if prompted.
4. Approve, return to your client and refresh its tool list.

For your own client implementation, follow the [OAuth guide](/mcp/oauth.md) for discovery, registration, PKCE and refresh-token handling.
{% endtab %}

{% tab title="API key" %}

1. Create a key in [Account settings → API keys](https://portal.kinesis.network/dashboard/account).
2. Choose scopes, organization or project restrictions, and expiry for your integration.
3. Supply the key through your client's secret mechanism or environment, and send this header on MCP requests:

```http
Authorization: Bearer kn_your_api_key
```

`kn_your_api_key` is a placeholder. Do not put the key in the URL, a prompt or a committed configuration file. Your agent needs `projects:read` to list projects; add other [scopes](/api/authentication.md) for its tasks.
{% endtab %}
{% endtabs %}

## Verify with read-only calls

With the default compact catalog, call tool **`account`**:

```json
{"action":"whoami","params":{}}
```

Then call **`account`** with:

```json
{"action":"list_orgs","params":{}}
```

Choose a returned organization slug and call **`projects`**:

```json
{"action":"list_projects","params":{"org":"acme"}}
```

Replace `acme` with that slug. For individual action names, see [catalog modes](/mcp/connect.md#choose-a-catalog-mode). Load `account` and `projects` if you apply a group filter and want to run these checks.

## Build a useful agent

Call `read_docs` with `{"topic":"getting_started"}` to learn the platform. Use `describe_action` to obtain a folded action's complete input schema before constructing complex requests. Successful calls return JSON in text content and `structuredContent`; failures include `isError` and a structured error.

Have the user choose the organization before organization-level work. Respect credential scopes, organization roles and each action's confirmation or spending requirements. Follow [agent workflows](/mcp/workflows.md) for polling, retries and idempotency.

The server is stateless. Use one JSON-RPC message per HTTP request; batches and change-event subscriptions are not supported. A client that accepts only local stdio processes needs remote HTTP support to use this endpoint directly.

[Shared connection options](/mcp/connect.md#connection-options) · [OpenAI profile](/mcp/openai-profile.md) · [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/custom-agent.md?ask=<question>&goal=<user_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.