> ## Documentation Index
> Fetch the complete documentation index at: https://docs.argentos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Platform Server

> Expose ArgentOS as an MCP server so Claude Desktop, Cursor, Claude Code, and any MCP client can operate your agent system remotely — memory, tasks, projects, and direct agent conversation.

## Overview

ArgentOS isn't just an MCP **client** (consuming external tool servers). It's also an MCP **Platform Server** — exposing the entire agent operating system over the Model Context Protocol.

This means any MCP-compatible tool can:

* Search and write to agent memory (MemU)
* Query and create tasks and projects
* Search the knowledge base (RAG library)
* List family agents, schedules, and workforce jobs
* **Talk directly to individual agents** — with full personality, tools, and memory
* **Convene the Think Tank** for multi-perspective debate

<Info>
  The MCP server runs on the gateway's existing HTTP port (`18789` by default). No additional services needed.
</Info>

## Quick Start

<Steps>
  <Step title="Verify the gateway is running">
    ```bash theme={null}
    argent gateway status
    ```

    The MCP endpoint is enabled by default on `/mcp`.
  </Step>

  <Step title="Find your gateway token">
    ```bash theme={null}
    cat ~/.argentos/argent.json | grep -A2 '"auth"'
    ```
  </Step>

  <Step title="Configure your MCP client">
    See the [client configuration](#client-configuration) section below.
  </Step>
</Steps>

## Client Configuration

<Tabs>
  <Tab title="Claude Desktop">
    Claude Desktop requires the `mcp-remote` stdio bridge. Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "argentos": {
          "command": "npx",
          "args": [
            "mcp-remote",
            "http://localhost:18789/mcp",
            "--header",
            "Authorization: Bearer <your-gateway-token>"
          ]
        }
      }
    }
    ```

    Restart Claude Desktop after saving. The `npx` call auto-installs `mcp-remote` on first run.
  </Tab>

  <Tab title="Claude Code">
    Add to `~/.claude.json` or your project's `.mcp.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "argentos": {
          "type": "streamable-http",
          "url": "http://localhost:18789/mcp",
          "headers": {
            "Authorization": "Bearer <your-gateway-token>"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Cursor / Windsurf">
    In your IDE's MCP settings:

    ```json theme={null}
    {
      "argentos": {
        "type": "streamable-http",
        "url": "http://localhost:18789/mcp",
        "headers": {
          "Authorization": "Bearer <your-gateway-token>"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Available Tools

ArgentOS exposes **16 tools** across 7 categories:

### Memory

| Tool            | Description                                                                   |
| --------------- | ----------------------------------------------------------------------------- |
| `memory_recall` | Search the agent's persistent memory (MemU) by keyword                        |
| `memory_store`  | Store a new memory with type classification, significance, and entity tagging |

### Knowledge

| Tool               | Description                                                         |
| ------------------ | ------------------------------------------------------------------- |
| `knowledge_search` | Search the RAG knowledge library with optional collection filtering |

### Tasks

| Tool           | Description                                                                                  |
| -------------- | -------------------------------------------------------------------------------------------- |
| `tasks_list`   | List tasks filtered by status (pending, in\_progress, blocked, completed, failed, cancelled) |
| `tasks_create` | Create a task with title, description, and priority                                          |

### Projects

| Tool             | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `projects_list`  | List projects with task counts and completion percentage |
| `project_detail` | Get a project with all child tasks and their status      |
| `project_create` | Create a project with child tasks in one call            |

### Operations

| Tool             | Description                                                            |
| ---------------- | ---------------------------------------------------------------------- |
| `family_list`    | List all family agents with name, role, team, and live presence status |
| `schedules_list` | List cron schedules and recurring jobs                                 |
| `jobs_list`      | List workforce job assignments with recent run history                 |

### System

| Tool           | Description                                                                                                  |
| -------------- | ------------------------------------------------------------------------------------------------------------ |
| `agent_status` | Agent name, model, gateway port, active MCP sessions, and local model health (LM Studio / Ollama up or down) |

### Conversation

| Tool         | Description                                                                          |
| ------------ | ------------------------------------------------------------------------------------ |
| `agent_chat` | Talk directly to any family agent (Argent, Forge, Quill, etc.)                       |
| `group_chat` | Message multiple agents by ID or team name, collect all responses                    |
| `think_tank` | Convene Think Tank panelists (Dario, Sam, Elon, Jensen) for multi-perspective debate |

<Tip>
  `agent_chat` runs through the full `agentCommand` pipeline — SOUL.md, memory, tools, model routing, personality. The agent's response is stored in their session transcript and processed by the memory extraction pipeline. It's not a stripped-down version.
</Tip>

## Tool Reference

<Accordion title="memory_recall">
  | Parameter | Type   | Required | Description                                                             |
  | --------- | ------ | -------- | ----------------------------------------------------------------------- |
  | `query`   | string | yes      | Search query — natural language or keywords                             |
  | `limit`   | number | no       | Maximum results (default 10)                                            |
  | `type`    | string | no       | Filter by memory type: profile, event, knowledge, behavior, skill, etc. |
</Accordion>

<Accordion title="memory_store">
  | Parameter      | Type      | Required | Description                                                     |
  | -------------- | --------- | -------- | --------------------------------------------------------------- |
  | `content`      | string    | yes      | The memory content to store                                     |
  | `type`         | enum      | no       | profile, event, knowledge, behavior, skill, tool, self, episode |
  | `significance` | number    | no       | Importance 1-10 (default 5)                                     |
  | `entities`     | string\[] | no       | People, places, or things referenced                            |
</Accordion>

<Accordion title="knowledge_search">
  | Parameter    | Type   | Required | Description                                 |
  | ------------ | ------ | -------- | ------------------------------------------- |
  | `query`      | string | yes      | Search query — natural language or keywords |
  | `limit`      | number | no       | Maximum results (default 10)                |
  | `collection` | string | no       | Filter by knowledge collection name         |
</Accordion>

<Accordion title="tasks_list">
  | Parameter | Type   | Required | Description                                                  |
  | --------- | ------ | -------- | ------------------------------------------------------------ |
  | `status`  | enum   | no       | pending, in\_progress, blocked, completed, failed, cancelled |
  | `limit`   | number | no       | Maximum results (default 20)                                 |
</Accordion>

<Accordion title="tasks_create">
  | Parameter     | Type   | Required | Description                                             |
  | ------------- | ------ | -------- | ------------------------------------------------------- |
  | `title`       | string | yes      | Task title                                              |
  | `description` | string | no       | Task description                                        |
  | `priority`    | enum   | no       | urgent, high, normal, low, background (default: normal) |
</Accordion>

<Accordion title="projects_list">
  | Parameter | Type   | Required | Description                  |
  | --------- | ------ | -------- | ---------------------------- |
  | `status`  | enum   | no       | Filter by project status     |
  | `limit`   | number | no       | Maximum results (default 20) |
</Accordion>

<Accordion title="project_detail">
  | Parameter | Type   | Required | Description |
  | --------- | ------ | -------- | ----------- |
  | `id`      | string | yes      | Project ID  |
</Accordion>

<Accordion title="project_create">
  | Parameter     | Type   | Required | Description                                                      |
  | ------------- | ------ | -------- | ---------------------------------------------------------------- |
  | `title`       | string | yes      | Project title                                                    |
  | `description` | string | no       | Project description                                              |
  | `priority`    | enum   | no       | urgent, high, normal, low, background (default: normal)          |
  | `tasks`       | array  | yes      | Child tasks — each with title, optional description and priority |
</Accordion>

<Accordion title="family_list">
  No parameters. Returns all registered family agents with id, name, role, team, status, and live `alive` presence check (via Redis heartbeat).
</Accordion>

<Accordion title="schedules_list">
  | Parameter         | Type    | Required | Description                                 |
  | ----------------- | ------- | -------- | ------------------------------------------- |
  | `includeDisabled` | boolean | no       | Include disabled schedules (default: false) |
</Accordion>

<Accordion title="jobs_list">
  | Parameter | Type   | Required | Description                  |
  | --------- | ------ | -------- | ---------------------------- |
  | `agentId` | string | no       | Filter by agent ID           |
  | `limit`   | number | no       | Maximum results (default 20) |
</Accordion>

<Accordion title="agent_status">
  No parameters. Returns agent name, primary model, gateway port, active MCP session count, and health status for local model backends:

  * **LM Studio** — probes `127.0.0.1:1234`
  * **Ollama** — probes `127.0.0.1:11434`
</Accordion>

<Accordion title="agent_chat">
  | Parameter  | Type   | Required | Description                                |
  | ---------- | ------ | -------- | ------------------------------------------ |
  | `message`  | string | yes      | The message to send                        |
  | `agentId`  | string | yes      | Agent ID (e.g. 'argent', 'forge', 'quill') |
  | `thinking` | enum   | no       | off, low, medium, high (default: off)      |

  Runs through the full agent pipeline. The agent gets their SOUL.md, memory context, tools, model routing — everything.
</Accordion>

<Accordion title="group_chat">
  | Parameter  | Type      | Required | Description                               |
  | ---------- | --------- | -------- | ----------------------------------------- |
  | `message`  | string    | yes      | The message to send to all agents         |
  | `agentIds` | string\[] | no       | Specific agent IDs to include             |
  | `team`     | string    | no       | Team name (e.g. 'dev-team', 'think-tank') |
  | `thinking` | enum      | no       | off, low, medium, high (default: off)     |

  Messages are sent sequentially. Each agent runs their full pipeline independently. Provide `agentIds`, `team`, or both.
</Accordion>

<Accordion title="think_tank">
  | Parameter   | Type      | Required | Description                            |
  | ----------- | --------- | -------- | -------------------------------------- |
  | `topic`     | string    | yes      | The debate topic or question           |
  | `panelists` | string\[] | no       | Specific panelists (default: all four) |
  | `thinking`  | enum      | no       | off, low, medium, high (default: low)  |

  Panelists: **Dario** (risk/safety via Claude), **Sam** (product/scaling via GPT), **Elon** (first principles via Grok), **Jensen** (infrastructure).
</Accordion>

## Configuration

```json theme={null}
{
  "gateway": {
    "mcp": {
      "enabled": true,
      "allowedTools": ["memory_recall", "tasks_list", "agent_status"]
    }
  }
}
```

| Field          | Type      | Default | Description                                              |
| -------------- | --------- | ------- | -------------------------------------------------------- |
| `enabled`      | boolean   | `true`  | Enable or disable the `/mcp` endpoint                    |
| `allowedTools` | string\[] | all     | Restrict which tools are exposed. Omit to expose all 16. |

## Authentication

All MCP requests require the gateway Bearer token:

```
Authorization: Bearer <gateway-token>
```

This is the same token used by the dashboard and WebSocket clients. Find it in `~/.argentos/argent.json` under `gateway.auth.token`. Unauthenticated requests receive HTTP 401.

## Transport

The MCP server uses **Streamable HTTP** transport (MCP SDK v1.28+):

| Method   | Path   | Purpose                                                |
| -------- | ------ | ------------------------------------------------------ |
| `POST`   | `/mcp` | JSON-RPC messages (initialize, tools/list, tools/call) |
| `GET`    | `/mcp` | SSE stream for server-to-client notifications          |
| `DELETE` | `/mcp` | Close a session                                        |

Sessions are created on the first `initialize` request. The server returns an `Mcp-Session-Id` header for subsequent requests.

## Security

<Warning>
  * **No filesystem access** — MCP tools cannot read, write, or execute files
  * **No shell commands** — `bash`, `exec`, `terminal` are never exposed
  * **No channel tools** — agents cannot send messages to external channels via MCP
  * **Auth mandatory** — same security boundary as the gateway
  * **ACL respected** — knowledge search honors collection-level access controls
  * **Think Tank is advisory** — panelists have read-only tool access
  * **Intent system active** — `agent_chat` respects intent hierarchy boundaries
</Warning>

Use `allowedTools` to further restrict the attack surface for specific deployments.