Configure AI Agents

Connect Cursor, Claude, Codex, or any MCP client to Kliq with an API key, OAuth, skills, and the 26-tool adapter.

Kliq is built for agents. One organization-scoped registry powers four surfaces:

Surface	When to use it
MCP `https://kliq.sh/api/mcp`	Cursor, Claude, Codex, and any MCP client
Tools REST `GET/POST /api/v1/tools`	Custom agents that call HTTP
Agent skill `GET /api/v1/agent-skill`	A SKILL.md the model can load
CLI `pnpm tools`	Repo-local shells wrapping the tools API

All 26 tools execute the same Admin API. The catalog is in Agent Tools. REST resources are in Admin API.

1. Create an API key

Open Settings → API Keys → Create Key. The dialog takes a name only (32 characters). Copy the nsk_… value immediately; it is shown once.

Dashboard-created keys receive this default scope set:

account:read, domains:read
links:read, links:write
analytics:read
events:write

They cannot list members or customers, archive links, register domains, or run imports. Rate limit is 1000 requests per hour per key. Store the key as KLIQ_API_KEY. Never put it in a prompt, repo, browser bundle, or log.

Confirm the organization:

curl https://kliq.sh/api/v1/me \
  -H "Authorization: Bearer $KLIQ_API_KEY"

x-api-key is accepted for compatibility. Bearer is preferred.

2. Connect MCP

The MCP server is streamable HTTP. All 26 tools are registered on connect. Auth is a bearer API key or OAuth 2.1. OAuth is owners and admins only; the issued token is scoped to the organization chosen on the consent screen. Default OAuth client scopes are read-only (account:read, domains:read, links:read, analytics:read) plus openid / profile / email. That cannot create links or track leads. Use an API key when the agent must write.

Discovery lives at /.well-known/oauth-protected-resource/api/mcp.

Cursor

Project file .cursor/mcp.json, or the user MCP config:

{
  "mcpServers": {
    "kliq": {
      "type": "http",
      "url": "https://kliq.sh/api/mcp",
      "headers": {
        "Authorization": "Bearer nsk_YOUR_KEY"
      }
    }
  }
}

If the client supports OAuth MCP, omit the header, add the URL, and complete the Kliq consent screen. The issued token is scoped to the organization you pick.

Claude Code

claude mcp add --transport http kliq https://kliq.sh/api/mcp \
  --header "Authorization: Bearer $KLIQ_API_KEY"

Claude Desktop / Claude.ai connectors

Use a streamable HTTP server with the same URL and bearer header. Restart the app after saving.

Codex / other MCP clients

Point the client at https://kliq.sh/api/mcp with Authorization: Bearer $KLIQ_API_KEY. Local development uses http://localhost:3060/api/mcp against a key issued on that deployment.

A successful handshake lists 26 tools (get_organization, create_parent_link, track_lead, …). A missing or invalid credential returns 401 instead of an empty catalog.

Omit --header (Claude Code) or the headers object (Cursor) to use OAuth instead of a long-lived key.

3. Install the agent skill

The live skill is the operational contract. Fetch it; do not copy a stale file from a gist.

mkdir -p ~/.claude/skills/kliq
curl -fsSL https://kliq.sh/api/v1/agent-skill \
  -o ~/.claude/skills/kliq/SKILL.md

Same URL with a .md suffix: /api/v1/agent-skill.md.

Agent	Where to put it
Claude Code	`~/.claude/skills/kliq/SKILL.md`
Cursor	`.cursor/skills/kliq/SKILL.md`
Codex / repo-shared	`.agents/skills/kliq/SKILL.md`

The skill tells the model to authenticate, fetch OpenAPI and /api/v1/tools, reuse idempotency keys, follow cursors, and treat DELETE /links/{id} as archive. Pair it with MCP so the model can actually call the tools. See Agent Tools for every tool name.

4. Call tools over HTTP

Same registry, no MCP required:

curl https://kliq.sh/api/v1/tools \
  -H "Authorization: Bearer $KLIQ_API_KEY"

curl https://kliq.sh/api/v1/tools/create_parent_link \
  -H "Authorization: Bearer $KLIQ_API_KEY"

curl -X POST https://kliq.sh/api/v1/tools/create_parent_link \
  -H "Authorization: Bearer $KLIQ_API_KEY" \
  -H "Content-Type: application/json" \
  --data '{
    "domainId": "DOMAIN_ID",
    "slug": "launch",
    "name": "Launch",
    "destinationUrl": "https://example.com",
    "idempotencyKey": "launch-v1"
  }'

Locally, from the repo:

export KLIQ_API_KEY=nsk_YOUR_KEY
export KLIQ_API_URL=https://kliq.sh
pnpm tools list
pnpm tools get create_parent_link
pnpm tools run create_parent_link '{"domainId":"DOMAIN_ID","slug":"launch","name":"Launch","destinationUrl":"https://example.com","idempotencyKey":"launch-v1"}'

Set x-tool-source to mcp or cli when you wrap the tools API. Bare HTTP defaults to api.

5. Agent rules that actually matter

Fetch /api/v1/openapi.json and /api/v1/tools at session start.
Reuse a stable business idempotencyKey on retries. A different payload with the same key returns 409.
Follow opaque pagination.cursor until isDone is true.
Analytics ranges are inclusive UTC days, max 367 days on the API.
Revenue is integer minor units plus a three-letter currency.
archive_link / DELETE /links/{id} stops redirects; it does not physically delete the URL.
After 429 or a transient 500, back off. Do not mint a new idempotency key.

Agent Tools — every tool, scope, and HTTP route
Admin API — REST resources, errors, pagination
Attribution and Events — track_lead / track_sale