How to connect ImonesMCP to Claude, Cursor, and other AI agents

Connecting ImonesMCP to an AI agent takes three moves: get access, point your client at the endpoint, and ask a question. OAuth-capable clients like Claude Desktop need no key at all; CLI and config-file clients use an API key as a bearer token. This tutorial covers the common clients, mirroring the docs exactly. New to MCP itself? Start with what MCP is.

Before you start

You need two things: access and the endpoint.

• Access. Most MCP clients open a browser sign-in automatically over OAuth — no key needed. For automation or CI, create an API key in your dashboard; keys look like rk_live_… and are shown once, so store it somewhere safe. Get a key and see the plans on the pricing page.
• Endpoint. ImonesMCP is a remote MCP server over Streamable HTTP. The endpoint URL is shown on the docs page and in your dashboard — copy it from there.

You do not need a paid plan to start: the Free plan includes tool calls each month with access to all six tools and no card required, so you can connect and run real queries before deciding whether to upgrade. Usage is metered per API key, so if you connect several agents, give each its own key to track them separately and revoke one without affecting the others.

Claude Desktop (OAuth)

Claude Desktop authenticates over OAuth, so there is no config file or API key to manage — just connect and sign in:

1. Open Claude Desktop and go to Settings → Connectors.
2. Click Add custom connector.
3. Paste the endpoint as the URL, name it ImonesMCP, and click Add.
4. Click Connect, sign in, and approve access — Claude discovers the tools automatically.

Claude Code / CLI (API key with header)

For Claude Code, add the server from your terminal with a single command:

claude mcp add --transport http imonesmcp ENDPOINT_URL

Replace ENDPOINT_URL with the endpoint from the docs page. Claude Code can sign in over OAuth — after adding the server, running /mcp opens your browser to authenticate — so no key is needed for interactive use. For CI or automation, pass an API key as a bearer token via a header instead, then restart your agent so it discovers the tools.

Cursor and other MCP clients

Config-file clients (Cursor, VS Code, Windsurf, and others) point at the same endpoint and send your API key as a bearer token. In Cursor, edit ~/.cursor/mcp.json:

{
  "mcpServers": {
    "imonesmcp": {
      "url": "ENDPOINT_URL",
      "headers": { "Authorization": "Bearer YOUR_API_KEY" }
    }
  }
}

Replace ENDPOINT_URL with the endpoint and YOUR_API_KEY with a key you create in the dashboard, then restart the client. VS Code uses .vscode/mcp.json with a servers block and "type": "http"; Windsurf uses ~/.codeium/windsurf/mcp_config.json with a serverUrl field. The docs show the exact snippet for each client, with copy buttons.

Custom agents on the MCP SDK

If you are building your own agent rather than using an off-the-shelf client, ImonesMCP behaves like any other remote MCP server. Add it to your agent's server list with the endpoint URL and an Authorization: Bearer YOUR_API_KEY header, and your MCP client library handles the rest of the handshake — it fetches the tool definitions and exposes the six tools to your model. Because the transport is Streamable HTTP, no local process or stdio bridge is needed; your agent connects directly over the network. Everything else in this guide — the endpoint, the bearer token, the verification prompt — applies unchanged.

Verify it works

Once connected, the agent discovers the six tools automatically. Confirm the connection with a real question — for example:

Find active Vilnius logistics companies with over one million euro
in revenue and VAT registered, sorted by revenue.

The agent should call search_companies and return matching companies with their codes, statuses, and revenue. If it does, you are connected. For a guided first lookup, see how to look up any Lithuanian company.

Troubleshooting

• The agent doesn't see any tools. Restart the client after adding the server so it re-runs tool discovery. Confirm the endpoint URL matches the one on the docs page exactly.
• Authentication fails on an OAuth client. Re-run the connect flow (in Claude Code, /mcp) and complete the browser sign-in. Approve the requested access when prompted.
• 401 or unauthorized with an API key. Check the Authorization header is Bearer YOUR_API_KEY with a valid, non-revoked key. Keys are shown once at creation — if you lost it, create a new one in the dashboard.
• Calls stop returning results. You may have hit your monthly quota. Usage is metered per key; the response includes a clear upgrade prompt. See pricing to move to Pro.

That is the whole setup. Point any MCP client at the endpoint, authenticate, and your agent can query every registered Lithuanian company. Full endpoint and tool reference is in the docs.