Quickstart

Two paths in: a sandbox API key (ck_…) for hand-rolled HTTP, MCP-over-HTTP, and quick smoke tests, or full MCP via OAuth for Claude Desktop, claude.ai, and Claude Code. Start with the sandbox key — it ships with your tenant.

Replace {tenant} in the URLs below with your tenant subdomain — e.g. https://acme.cognethics.com if your subdomain is acme. No tenant yet? Request one at developers.cognethics.com/signup/.

Verify your sandbox key

When your tenant was provisioned we issued a ck_-prefixed sandbox key bound to your account. It works against /api/v1/dev/* — three endpoints designed for end-to-end auth verification. Manage it (rotate, revoke, mint more) at the developer dashboard.

The key accepts either header form:

Header form	Example
`Authorization: Bearer …`	`Authorization: Bearer ck_a1b2…`
`X-API-Key: …`	`X-API-Key: ck_a1b2…`

Smoke-test the key against /api/v1/dev/me/:

curl -H "Authorization: Bearer ck_REPLACE_ME" \
  https://{tenant}.cognethics.com/api/v1/dev/me/

Expected response shape:

{
  "authenticated": true,
  "key": {
    "prefix": "ck_a1b2c3d4",
    "name": "Sandbox key",
    "created_at": "2026-05-06T17:00:00+00:00",
    "last_used_at": "2026-05-06T17:00:42+00:00",
    "scopes": []
  },
  "user": { "id": "...", "email": "[email protected]" },
  "tenant": { "id": "...", "name": "...", "subdomain": "..." }
}

Same call from Python (no SDK needed — pure requests):

import os, requests

r = requests.get(
    f"https://{os.environ['COGNETHICS_TENANT']}.cognethics.com/api/v1/dev/me/",
    headers={"Authorization": f"Bearer {os.environ['COGNETHICS_DEV_KEY']}"},
    timeout=10,
)
r.raise_for_status()
print(r.json())

Sibling endpoints under the same namespace:

GET /api/v1/dev/ping/ — no auth, smoke-test the namespace itself.
GET /api/v1/dev/echo/ — echoes back your query params and tenant subdomain; useful for debugging proxies.

Call MCP with your sandbox key

The same ck_ key works against the MCP server at /api/mcp/mcp — pass it in the Authorization: Bearer … header. The key inherits your tenant's full permission scope — see /auth/ for the per-app permission model.

List the tools your tenant exposes via JSON-RPC:

curl -X POST "https://{tenant}.cognethics.com/api/mcp/mcp" \
  -H "Authorization: Bearer ck_REPLACE_ME" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'

Same call from Python:

import os, requests

r = requests.post(
    f"https://{os.environ['COGNETHICS_TENANT']}.cognethics.com/api/mcp/mcp",
    headers={
        "Authorization": f"Bearer {os.environ['COGNETHICS_DEV_KEY']}",
        "Content-Type": "application/json",
        "Accept": "application/json, text/event-stream",
    },
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}},
    timeout=30,
)
r.raise_for_status()
print(r.json())

Connect Claude (MCP via OAuth)

Cognethics speaks the standard Model Context Protocol over HTTP+SSE with OAuth 2.1 + PKCE. Most MCP-aware clients negotiate the OAuth flow automatically — pick yours below.

Claude Desktop

Open Claude Desktop → Settings → Developer → Edit Config.

Add Cognethics to the mcpServers block:

{
  "mcpServers": {
    "a4": {
      "url": "https://{tenant}.cognethics.com/api/mcp/sse"
    }
  }
}

Restart Claude Desktop. The first connection triggers OAuth approval in your browser. Pick a scope (mcp:read, mcp:write, or mcp:execute) and approve.

First useful prompt: "List my work orders due this week and group them by priority."

claude.ai

Open claude.ai → Settings → Connectors → Add custom MCP.

Paste this URL:

https://{tenant}.cognethics.com/api/mcp/sse

Browser-based Dynamic Client Registration handles the OAuth flow. Approve the scope set you want and you're connected.

First useful prompt: "Show me overdue invoices and draft a chase email to the top 3 vendors."

Claude Code (CLI)

Edit ~/.claude/settings.json (or run claude config):

{
  "mcpServers": {
    "a4": {
      "url": "https://{tenant}.cognethics.com/api/mcp/sse",
      "type": "http"
    }
  }
}

Restart your Claude Code session.
Type /mcp to confirm Cognethics is connected. You should see the Cognethics server listed with all tool groups.

First useful prompt: "Pull the maintenance history for Engine 1 from Cognethics and summarize anomalies."

Troubleshooting

HTTP code	Meaning	Fix
401	Token expired or missing	Restart your client to refresh OAuth, or re-check the `Authorization` header on a sandbox-key call.
403	Scope insufficient	Re-approve OAuth with a broader scope (`mcp:execute`), or rotate the sandbox key from the dashboard.
404	Tenant URL wrong	Double-check `{tenant}.cognethics.com` matches your subdomain.
429	Rate-limit hit	Slow down or check `FederationQuota` with your tenant admin.

Where to manage keys

Sandbox ck_… keys → developer dashboard. OAuth tokens → handled automatically by your MCP client; details on /auth/.

Next: explore the handler catalog or browse recipes.