---
title: "Connect to the igeo.ai MCP server"
description: "Configure the igeo.ai MCP HTTP endpoint, discover tools, and use live workspace data for weekly prompt planning."
url: "https://www.igeo.ai/developers/mcp/"
language: "en"
---

BUILD WITH igeo.ai[Read as Markdown ↗](https://www.igeo.ai/developers/mcp.md)

# Connect to the igeo.ai MCP server

The igeo.ai MCP endpoint accepts JSON-RPC 2.0 requests over HTTP at `https://api.igeo.ai/mcp`. Compatible clients can discover tools and resources, read workspace data, and call supported named write tools. MCP tool and resource access requires a workspace owner, admin, or editor role.

## Configure your client

Create a key in [MCP & API keys](https://app.igeo.ai/mcp-api-keys) and copy the configuration generated for your workspace. For a client accepting an `mcpServers` configuration with HTTP headers, the shape is:

```json
{
  "mcpServers": {
    "igeo": {
      "url": "https://api.igeo.ai/mcp",
      "headers": {
        "Authorization": "Bearer <YOUR_API_KEY>",
        "X-Workspace-Id": "<YOUR_WORKSPACE_ID>"
      }
    }
  }
}
```

Client configuration formats vary. Use the client's remote HTTP MCP option and preserve both authentication values. Keep keys outside shared configuration files. Clients using hosted OAuth should follow the [OAuth discovery details](https://www.igeo.ai/developers/auth/).

## Initialize and discover

The following examples are JSON request bodies sent to `POST /mcp` with the authentication headers above and `Content-Type: application/json`.

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": {},
    "clientInfo": { "name": "workspace-integration", "version": "1.0.0" }
  }
}
```

Use the negotiated protocol version returned by the server. A standard MCP client handles its initialization lifecycle. Discover the current tool schemas next:

```json
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {} }
```

Discover supported read routes through MCP itself:

```json
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": { "name": "allowed_routes", "arguments": {} }
}
```

The same route catalog is available through `resources/read` using URI `igeo://mcp/allowlisted-get-routes`. Use `resources/list` to discover resources. The server also exposes a prompt-planning playbook at `igeo://mcp/playbooks/prompt-prioritization`.

## Run a weekly planning read

```json
{
  "jsonrpc": "2.0",
  "id": 4,
  "method": "tools/call",
  "params": {
    "name": "prompt_work_priorities",
    "arguments": { "recentDays": 30, "query": { "range": 7 } }
  }
}
```

This read returns recently worked prompts, a maintenance pick, an improvement pick, and alternatives. `recentDays` controls the lookback for post activity; `query.range` controls the visibility window. The defaults are 30 days of activity and seven days of visibility. A pick can be empty. Describe only results returned for the selected workspace.

Useful follow-up tools include `prompts`, `topics`, `competitors`, `prompt_responses`, and `posts`. Use the discovered schema for arguments and retain returned IDs. Prefer named tools. The advanced `api_get` tool accepts a full path matching `allowed_routes`; it does not accept guessed bare paths.

## Handle pagination and writes deliberately

For supported lists, omitting pagination lets MCP combine pages, with a cap of 50 upstream pages and 5,000 merged items. Check `_mcpPagination` for counts and truncation. Supply explicit pagination, such as `query.take` and `query.skip`, when you want one page.

Named writes include topic, prompt, tag, and competitor management, Brand Hub updates, and content generation or editing. Read existing state, review the proposed action, and use only tools discovered from the server. Check HTTP status, JSON-RPC errors, and tool `isError` before treating a call as successful. A JSON-RPC request ID correlates responses; it does not provide idempotency for mutations.

See [authentication and retry guidance](https://www.igeo.ai/developers/auth/), the [REST API guide](https://www.igeo.ai/developers/api/), and [product MCP documentation](https://app.igeo.ai/docs/mcp).

---

Source: https://www.igeo.ai/developers/mcp/

[Documentation index](https://www.igeo.ai/llms.txt) · [Developer documentation](https://www.igeo.ai/developers/)