> ## Documentation Index
> Fetch the complete documentation index at: https://inkbox.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Cloudflare Agents

> Connect a Cloudflare Agents SDK application to Inkbox over remote MCP with an API key or OAuth.

Connect your Cloudflare Agents SDK application to `https://inkbox.ai/mcp/cloudflare` to use an Inkbox identity's email, messaging, calls, contacts, notes, and Agent-to-Agent tools.

Your agent connects to Inkbox's remote MCP service. You do not need to host an Inkbox server or apply for a marketplace listing to make this direct connection.

## Connect with an API key

1. Create a claimed identity-scoped [API key](https://inkbox.ai/docs/api-keys.md) in the [Inkbox Console](https://inkbox.ai/console).
2. Add it to your application's secret bindings as `INKBOX_API_KEY`. Keep the value out of source control, browser code, and logs.
3. Add a connection method to your existing `Agent` class:

```ts theme={null}
import { Agent } from "agents";

interface Env {
  INKBOX_API_KEY: string;
}

export class InkboxAgent extends Agent<Env> {
  async connectInkbox() {
    return this.addMcpServer("Inkbox", "https://inkbox.ai/mcp/cloudflare", {
      transport: {
        type: "streamable-http",
        headers: { "X-API-Key": this.env.INKBOX_API_KEY },
      },
    });
  }
}
```

4. Call `connectInkbox()` from your application's authorized setup flow. Set it up once; the SDK reuses a connection with the same name and URL and persists it across restarts. You do not need to add it for every message.
5. Wait for the connection to become ready, then expose its discovered tools to your agent's model using the SDK's [MCP client integration](https://developers.cloudflare.com/agents/model-context-protocol/apis/client-api/).

This example is a connection method, not a complete agent deployment. Keep your application's routing and agent configuration. One shared API key grants the same identity's access to every caller of that agent; use separate credentials or per-user OAuth for separate users.

The SDK also persists the configured transport headers, including `X-API-Key`, in your agent's Durable Object storage. Treat that stored connection configuration as a credential.

## Use OAuth instead

For user-authorized access, omit the `X-API-Key` header and connect to the same URL. The SDK manages the OAuth flow. If `addMcpServer` returns `state: "authenticating"`, send that user to its `authUrl` to choose an Inkbox organization and identity and approve access.

Configure the SDK's callback route and public callback host for your deployment, following [Cloudflare's OAuth setup](https://developers.cloudflare.com/agents/model-context-protocol/apis/client-api/#oauth-authentication). Confirm that the connection reaches `ready` after authorization. OAuth access is bound to `https://inkbox.ai/mcp/cloudflare`; tokens issued for another Inkbox endpoint cannot be reused here.

Each OAuth authorization creates an independent connection. Connecting another
identity—or the same identity again—with the same OAuth client does not disconnect
existing connections. Each connection keeps its own identity access and refresh
credentials. Revoking one connection's refresh token does not revoke its siblings;
account or organization access changes can still affect multiple connections.

## Verify the connection

Call `inkbox_identity_get` through the discovered tools and confirm the selected identity. Try a read-only action before requesting a send or call. The endpoint provides ordinary MCP tools without interactive MCP views; available actions follow the identity's access.

See [Connect with MCP](https://inkbox.ai/docs/mcp-server.md) for the tool capabilities and data-access details.

## Scheduled work and incoming events

Use your agent application's [scheduler](https://developers.cloudflare.com/agents/agent-class/schedule-tasks/) for scheduled work. Adding an MCP connection does not schedule runs or automatically wake the agent when a message arrives.

MCP Events require identity-bound OAuth and a client that implements the subscription and callback flow. API-key connections do not grant Events access. Do not assume that connecting through the SDK enables these callbacks. See [Inkbox background tasks](https://inkbox.ai/docs/mcp-server.md#set-up-background-tasks).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.