# Connect Agentik to your agent

Agentik gives an AI agent one connection to discover, inspect and use tools from multiple providers. This guide configures that connection and checks it without executing a provider tool.

For a connector's server URL, copy the authenticated endpoint below. /connect.md is a guide, not an MCP server. If a connector uses /connect.md, replace its URL (or recreate it), then reconnect and complete OAuth again.

- Transport: Streamable HTTP
- Authenticated MCP endpoint: https://ai.agentik.cc/mcp
- Public discovery and inspection endpoint: https://ai.agentik.cc/mcp/public
- Workspace API keys: https://www.agentik.cc/dashboard/keys
- Account sign-in: https://www.agentik.cc/account/sign-in
- API reference: https://api.agentik.cc/openapi.json
- API documentation: https://api.agentik.cc/llms.txt

## 1. Choose the right setup

Identify the intended app, including its surface. Respect an explicitly selected target even when a different agent reads this guide. Otherwise ask the user which app they want to connect; do not infer it from the current caller. “Claude Desktop” normally means the Chat or Cowork experience: use its account connector settings below. Use the Claude Code Desktop recipe only for an explicitly selected Code tab with a local project. If the target and available tools disagree, clarify the intended tab before editing files or directing the user elsewhere. Do not install every client. Explain the proposed configuration change and obtain the user's approval before applying it, unless they already approved that exact client and scope.

Inspect only the relevant MCP configuration. Keep existing servers and settings. If an existing connection already uses the same endpoint, reuse it regardless of its name; ask before replacing a different connection. Never overwrite a whole settings file or turn off client approval controls.

Prefer OAuth for the authenticated endpoint. The user approves access in their signed-in Agentik account at https://www.agentik.cc/connect/agent. Agentik creates a workspace when requested and a dedicated execution key with the approved permissions. The OAuth client receives its scoped tokens through the existing PKCE callback. The setup link does not authenticate its recipient. Never ask for a key in chat.

For a custom agent runtime or SDK application, use the standalone helper described under "Custom API/CLI runtime" below. No repository checkout is required. Hosted clients with native OAuth should keep their native flow.

Optional funding uses hosted Checkout and becomes confirmed only after server reconciliation. Sandbox credits never enable provider execution. Only resume a paid task that the user has already authorized. Never read or print credential files or environment values.

The account pages above belong to this deployment. If sign-in or workspace access is unavailable, report that blocker accurately. Do not claim an account was created or the connection succeeded. Offer the public discovery endpoint below for exploration.

## 2. Configure only the selected client

### Claude Code Desktop (Code tab)

Keep the user in the Desktop Code tab. For a local session, Desktop reads project .mcp.json and user ~/.claude.json. With permission to modify that project, merge a server named agentik with type "http" and url "https://ai.agentik.cc/mcp" into .mcp.json, preserving other entries. Alternatively guide the user through + next to the prompt, Connectors, and the custom-connector settings when available. Complete browser OAuth and reload or reconnect the local Code session if needed. Do not replace this target with a terminal onboarding or claim that this config also connects Claude Chat. Cloud/WSL sessions have different connector availability; explain the exact limitation instead of modifying local settings for a remote session.

### Claude Code terminal

After approval for user-level setup, run:

```sh
claude mcp add --transport http --scope user agentik https://ai.agentik.cc/mcp

# In Claude Code, open /mcp and authenticate Agentik.
```

Let the user complete the browser authorization. Reload or reconnect the MCP server if the current session does not yet expose it. A successful configuration command alone does not prove authentication.

### Codex

After approval for the user's Codex configuration, run:

```sh
codex mcp add agentik --url https://ai.agentik.cc/mcp
codex mcp login agentik
```

Let the user finish authorization in their browser. If no terminal is available, guide them to add a Streamable HTTP server in Codex's MCP settings using the endpoint above and authenticate there.

### Cursor

After approval, merge this entry into ~/.cursor/mcp.json, retaining any other servers:

```json
{
  "mcpServers": {
    "agentik": {
      "url": "https://ai.agentik.cc/mcp"
    }
  }
}
```

In Cursor's MCP settings, enable Agentik and complete the browser authorization. If filesystem access is unavailable, give the user these instructions and snippet instead of claiming to have installed it.

### Claude (web and desktop)

A chat prompt cannot create the custom connector on the user's behalf. Stay in the user's Chat or Cowork experience; no terminal, local settings file or Code tab is needed. Open Customize → Connectors (https://claude.ai/customize/connectors) with the same Claude account as Desktop, choose + → Add custom connector, name it Agentik, and paste:

```text
https://ai.agentik.cc/mcp
```

Leave advanced OAuth fields empty. Add the connector, choose Connect, and complete OAuth with the user's Agentik account in the browser. Return to the original Claude conversation, enable Agentik through + → Connectors, then run the connection check below. Keep the Agentik onboarding tab open: approval and authenticated verification update it separately. Account and organization permissions may limit custom connectors; Team/Enterprise owners must add the connector before members can connect it.

### ChatGPT

A chat prompt cannot create a custom app by itself. Check that the user's plan and workspace permissions allow custom MCP apps and developer mode. An authorized user can create an app in Apps settings, name it Agentik, choose OAuth and use:

```text
https://ai.agentik.cc/mcp
```

Scan tools, complete the browser authorization, create the app and select it in the conversation. If the setting is absent, explain the client requirement and link the official instructions below. Do not request an admin credential or change workspace permissions. Publishing an app to a whole organization is outside this setup.

### Hermes

Merge the following into ~/.hermes/config.yaml, preserving the existing configuration:

```yaml
mcp_servers:
  agentik:
    url: "https://ai.agentik.cc/mcp"
    auth: oauth
```

Complete authorization with Hermes Desktop's MCP Authorize action, or run `hermes mcp login agentik` from an available terminal. Reload MCP in the intended session after authorization. Native OAuth handles discovery and PKCE; do not read its saved token file. If no configuration access is available, provide the precise supported setting rather than claiming to have changed it.

### Muse and custom API/CLI runtimes

Muse is https://muse.ai/. Muse documents custom API/CLI connectors in its own runtime, but native custom MCP registration is not confirmed. Use the standalone Agentik runtime helper below in the SAME environment that runs Muse. This is a custom runtime integration, not a native Muse MCP installation. If Node 24, private persistent storage or outbound HTTPS is unavailable, explain that blocker instead of switching to another app.

### Custom API/CLI runtime

Retrieve the manifest from https://www.agentik.cc/agent-runtime/manifest.json and the standalone script from https://www.agentik.cc/agent-runtime/agentik-connect-81d2761e92c490d1.mjs. Its SHA-256 must equal 81d2761e92c490d1645170d5970729f4d54854c86ede9f37a1766bb1f142311a. Verify the downloaded bytes before execution; reject a mismatch. Use Node 24 or later. Choose a private persistent directory outside repositories, with owner-only permissions. Keep the script separate from its credential state. Never read the credential state into agent context or print it.

Run the verified helper with `--api https://api.agentik.cc --name "Muse" --state-file /absolute/private/agentik-credential.json` in the intended runtime. The helper returns a browser approval URL. Forward that URL to the user and wait for account consent. It creates or reuses the workspace, receives its encrypted credential privately, and verifies authenticated MCP inspection without executing a provider tool. Rerun the same command and state path to resume safely.

After approval, append `--call get_account` to read the real balance, or `--call discover_tools --input '{"query":"currency exchange","limit":3}'` to discover. The helper makes authenticated calls without exposing its credential to the agent. To inspect, use `--call inspect_tool --input '{"tool_id":"<actual discovered ID>"}'`. Do not invoke run_tool during installation.

For a later task the user explicitly authorized, inspect first, collect required inputs and price, then call run_tool through the helper. Keep its run ID and use get_run until final settlement. For an explicitly requested top-up, use prepare_topup to return the human review link; only the human approves Checkout. Use get_account to read the real top-up status and balance. Never treat an opened payment link as settled credit, enable automatic recharge or repeat a paid run to check status.

### Other clients

Use the authenticated endpoint above with Streamable HTTP and OAuth discovery. If the client cannot use OAuth but securely supports bearer credentials, use its secret store for a workspace API key. Do not invent an integration for a client without remote MCP support; provide the API reference instead.

## Optional: API-key configuration for local clients

Use this path only when the user chooses API-key authentication instead of OAuth. Have the user set AGENTIK_API_KEY privately in the environment that launches the client. Do not request, inspect or echo its value. Merge only the selected snippet. The placeholders below are literal environment references, not credentials to replace in chat or commit to a repository.

### Claude Code: .mcp.json

```json
{
  "mcpServers": {
    "agentik": {
      "type": "http",
      "url": "https://ai.agentik.cc/mcp",
      "headers": {
        "Authorization": "Bearer ${AGENTIK_API_KEY}"
      }
    }
  }
}
```

### Codex: ~/.codex/config.toml

```toml
[mcp_servers.agentik]
url = "https://ai.agentik.cc/mcp"
bearer_token_env_var = "AGENTIK_API_KEY"
```

### Cursor: ~/.cursor/mcp.json

```json
{
  "mcpServers": {
    "agentik": {
      "url": "https://ai.agentik.cc/mcp",
      "headers": {
        "Authorization": "Bearer ${env:AGENTIK_API_KEY}"
      }
    }
  }
}
```

New Agentik keys have no optional spending caps, tool restrictions or expiry by default. Only add a daily, hourly, lifetime or per-tool spending limit, a tool allowlist, network restriction or expiry if the user requests it. Normal workspace balance, tool availability and platform rate limits still apply.

## Explore without a workspace key

For discovery and inspection only, a compatible remote MCP client can use https://ai.agentik.cc/mcp/public without a bearer credential or OAuth. Explicitly label this connection read-only. Use a separate name such as agentik-catalog so it cannot silently replace an authenticated connection.

The public endpoint lists and authorizes only discover_tools and inspect_tool. It cannot run provider tools or read workspace executions. Hosted clients still require their normal custom-connector permissions. This is an exploration option, not a completed authenticated setup.

## 3. Check the connection without spending

After the client has connected and exposed Agentik's tools:

1. Call discover_tools with {"query":"web search","limit":3}.
2. Take an actual tool_id from those results and call inspect_tool with {"tool_id":"<the returned tool_id>"}. Do not fabricate a tool identifier.
3. Report the returned tool name, availability, required inputs and pricing. Distinguish a price from a maximum reservation; explain variable pricing when applicable.

Do not call run_tool or get_run during this setup. Do not execute a provider tool, create a payment, add credit, enable auto-recharge, change account policies or start a background task. Payment availability depends on the deployment and workspace; new workspaces start with zero credit. The connection check never requires a payment.

Only say the connection is verified when the actual discover_tools and inspect_tool calls succeed. If a client needs reloading, user authorization, account access or network access, state the remaining step. If only the public endpoint was checked, say "Public catalog connected; authenticated tool use is not connected yet."

When the user later asks to use a tool, inspect its current contract first, collect missing inputs, explain its price and follow the client's normal approval flow. Agentik also exposes run_tool for execution and get_run for following an existing run. Neither is needed to finish this installation check.

## Client documentation

- [Claude Desktop](https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp)
- [Claude Code Desktop](https://code.claude.com/docs/en/desktop)
- [Claude Code](https://code.claude.com/docs/en/mcp)
- [ChatGPT](https://help.openai.com/en/articles/12584461)
- [Codex](https://developers.openai.com/codex/mcp)
- [Cursor](https://cursor.com/docs/mcp)
- [Hermes](https://hermes-agent.nousresearch.com/docs/user-guide/features/mcp/)
- [Muse](https://security.muse.ai/)
- [Other clients](https://modelcontextprotocol.io/docs/develop/connect-remote-servers)