Connect Claude to aqoon

aqoon works with Claude Desktop and Claude Code through the Model Context Protocol (MCP). Once connected, Claude can search your knowledge base directly during conversations — no copy-pasting required.

Claude Desktop (Connectors)

The easiest way to connect Claude Desktop. No config files or terminal commands needed.

Step 1: Add aqoon as a connector

You only need to do this once:

1. Open Claude Desktop
2. Click Customize (bottom-left)
3. Click Connectors in the sidebar
4. Click the + icon at the top
5. Select Add custom connector
6. Fill in the form:
   • Name: aqoon
   • URL: https://aqoon.ai/mcp/
7. Click Save

Step 2: Connect

1. In the Connectors list, find aqoon and click Connect
2. Your browser opens — log in with your aqoon account
3. Click Approve on the consent page
4. Done! Claude Desktop can now search your knowledge base.

This creates a full-access API key automatically. You can view and revoke it from API Keys in your dashboard.

Claude Code & API Keys

For Claude Code or if you prefer manual setup, you will need an API key. Create one from API Keys in the sidebar. A full-access key is the right choice for personal use.

This connects Claude directly to aqoon over the internet. Claude Code needs no extra dependencies. Claude Desktop requires Node.js ≥ 18 for the mcp-remote bridge.

Claude Code

Run this command once in your terminal, replacing your-instance and aqn_your_api_key with your actual values:

claude mcp add aqoon --transport http https://your-instance/mcp \
  --header "Authorization: Bearer aqn_your_api_key"

Claude Desktop

Open your Claude Desktop configuration file (claude_desktop_config.json) and add the following inside the mcpServers block. This uses mcp-remote to bridge Claude Desktop to the remote server (requires Node.js).

{
  "mcpServers": {
    "aqoon": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://your-instance/mcp",
        "--header",
        "Authorization: Bearer aqn_your_api_key"
      ]
    }
  }
}

Restart Claude Desktop after saving the file. The first launch may take a moment while mcp-remote is installed.

Option B: Local Package

If you prefer to run a local MCP server on your machine, install the aqoon-mcp package. This requires Python to be installed.

pip install aqoon-mcp

Claude Code

claude mcp add aqoon aqoon-mcp \
  -e AQOON_URL=https://your-instance \
  -e AQOON_API_KEY=aqn_your_api_key

Claude Desktop

Add the following to claude_desktop_config.json:

{
  "mcpServers": {
    "aqoon": {
      "command": "aqoon-mcp",
      "env": {
        "AQOON_URL": "https://your-instance",
        "AQOON_API_KEY": "aqn_your_api_key"
      }
    }
  }
}

Restart Claude Desktop after saving the file.

Verifying the Connection

After setting up, start a new conversation in Claude and ask:

"List the collections in my aqoon knowledge base."

If Claude responds with your collection names, the connection is working. See MCP Tools & Usage for a full list of what Claude can do with aqoon.

Troubleshooting

Problem	Cause	Fix
"Could not load app settings" with command: Required	Claude Desktop does not support "type": "http" or "type": "streamable-http" directly	Use the mcp-remote config shown above (with "command": "npx")
Server disconnected / SyntaxError: node:fs/promises	Node.js version is too old (< 18)	Install Node.js ≥ 18. If using nvm: nvm alias default 22. Or use the full path in the config: "command": "/path/to/node/v22/bin/npx"
Server disconnected (no error in logs)	Stale npx cache from an older Node version	Delete the cache: rm -rf ~/.npm/_npx/ and restart Claude Desktop
Claude doesn't use aqoon tools	Server not listed in Claude's tools	Click the plug icon in Claude Desktop to check. If missing, restart Claude Desktop