MCP server

Connect an AI client

Configuration for Claude Desktop, Claude Code, Cursor and generic MCP clients, plus how to verify the connection works.

Planned design

The MCP server described here is the planned design layered on top of the agency REST gateway, which is live today. Until the server ships, everything on this page can be done with the REST endpoints in the API section.

Before you start

1
Create an API key
In Aisoiq go to Agency → Automations → API and create a key. Give it the read scope only for your first connection; you can create a second write-capable key later.
2
Note which clients the key can reach
A key is scoped to the clients you select. The assistant can only pass those client_id values.
3
Store the key in your shell profile
Keep it out of config files that sync or get committed.
bash
```
export AISOIQ_API_KEY="agx_live_..."
```

Client configuration

Edit claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\), then restart Claude.

json

{
  "mcpServers": {
    "aisoiq": {
      "command": "npx",
      "args": ["-y", "@aisoiq/mcp-server"],
      "env": {
        "AISOIQ_API_KEY": "agx_live_..."
      }
    }
  }
}

Verify the connection

1
Check the tool list
Ask the assistant "what Aisoiq tools do you have?". It should list the read tools, and write tools only if your key has the write scope.
2
Run a harmless read
Ask it to list your clients. This calls list_clients, which needs nothing but a valid key.
3
Confirm scoping
Ask for a client the key should not reach. The gateway returns 403 and the assistant should report that it has no access rather than inventing an answer.

Common problems

Symptom	Likely cause	Fix
No Aisoiq tools appear	Config file not reloaded, or JSON is invalid	Validate the JSON and fully quit and reopen the client, a window reload is not always enough.
Every call returns 401	Key missing from `env`, or the key was revoked	Re-create the key and confirm the env var is set in the process that launches the server.
Only read tools appear	Key has the `read` scope	Create a key with `write` (or `*`) and point the client at it.
403 on a specific client	Key is not scoped to that client	Edit the key in Agency → Automations → API and add the client.
Calls time out on long jobs	Audits and article generation are asynchronous	The tool returns a job reference; poll the matching read tool instead of waiting.