npm package: @ordo.space/mcp-server
Description: MCP Server for Ordo - Control Plane for AI Agents
Author: Ordo Team
Latest version: 0.5.0

# @ordo/mcp-server

MCP (Model Context Protocol) Server for [Ordo](https://ordo.ai) — Control Plane for AI Agents.

This server enables AI agents (like Claude in Cursor) to integrate with Ordo for:
- **Activity Tracking** — Track decisions, LLM calls, tool usage
- **Cost Monitoring** — Monitor token usage and spending
- **Trust Scoring** — Build trust through consistent behavior
- **Policy Enforcement** — Respond to governance rules

## Installation

### Using npx (Recommended)

No installation needed:

```bash
ORDO_API_KEY=your_key npx @ordo.space/mcp-server
```

### Global Install

```bash
npm install -g @ordo.space/mcp-server
```

Then run:

```bash
ORDO_API_KEY=your_key ordo-mcp
```

## Setup in Cursor

Add to your `.cursor/mcp.json`:

```json
{
  "mcpServers": {
    "ordo": {
      "command": "npx",
      "args": ["-y", "@ordo.space/mcp-server"],
      "env": {
        "ORDO_API_URL": "https://api.ordo.ai",
        "ORDO_API_KEY": "your_api_key_here",
        "ORDO_AGENT_NAME": "cursor-agent"
      }
    }
  }
}
```

## Environment Variables

| Variable | Required | Default | Description |
|----------|----------|---------|-------------|
| `ORDO_API_KEY` | Yes | - | Your Ordo API key (get from Settings > API Keys) |
| `ORDO_API_URL` | No | `http://localhost:3333` | Ordo API URL |
| `ORDO_AGENT_NAME` | No | `cursor-agent` | Name for this agent |
| `ORDO_AUTO_TRACKING` | No | `true` | Enable automatic tool call tracking |

## Auto-Tracking

Starting from v0.3.0, the MCP server includes **automatic telemetry** that tracks all tool calls without requiring explicit tracking calls.

### How It Works

```
┌─────────────────────────────────────────────────────────────────┐
│                      MCP Server                                 │
├─────────────────────────────────────────────────────────────────┤
│  Level 1: AUTO-TELEMETRY (always on by default)                │
│  • Tracks ALL tool calls automatically                          │
│  • Minimal data: tool_name, timestamp, duration, success       │
│  • Source: "auto" — separate from explicit tracking            │
│  • Fire-and-forget — never blocks agent execution              │
├─────────────────────────────────────────────────────────────────┤
│  Level 2: SEMANTIC TRACKING (explicit calls)                   │
│  • Agent calls ordo_track_* tools                               │
│  • Rich data: reasoning, confidence, context                   │
│  • Source: "explicit" — higher detail                          │
│  • Recommended for important decisions                          │
└─────────────────────────────────────────────────────────────────┘
```

### Benefits

- **Never miss data**: Even if agent forgets to track, baseline telemetry is captured
- **No performance impact**: Tracking is async and non-blocking
- **No conflicts**: Auto-tracking and explicit tracking complement each other
- **Opt-out**: Set `ORDO_AUTO_TRACKING=false` to disable

### Excluded Tools

Auto-tracking ignores Ordo tracking tools themselves to avoid infinite loops:
- `ordo_start_task`, `ordo_track_decision`, `ordo_track_llm_call`
- `ordo_track_tool_call`, `ordo_track_error`, `ordo_complete_task`
- `ordo_check_status`

## Available Tools

### Task Management

#### `ordo_start_task`
Start tracking a new task or workflow.

```json
{
  "task_id": "pr-review-123",
  "task_name": "Review Pull Request",
  "subject_type": "pull_request",
  "subject_id": "PR-123"
}
```

#### `ordo_complete_task`
Mark a task as complete.

```json
{
  "task_id": "pr-review-123",
  "status": "completed",
  "summary": "Approved with minor suggestions"
}
```

### Event Tracking

#### `ordo_track_decision`
Track a decision made by the agent.

```json
{
  "action": "approve",
  "confidence": 0.95,
  "reasoning": "Code follows best practices",
  "task_id": "pr-review-123"
}
```

#### `ordo_track_llm_call`
Track an LLM API call for cost monitoring.

```json
{
  "model": "claude-3.5-sonnet",
  "tokens": 1500,
  "latency_ms": 2100
}
```

#### `ordo_track_tool_call`
Track a tool or function call.

```json
{
  "tool_name": "github_api",
  "tool_input": { "action": "get_pr" },
  "success": true,
  "latency_ms": 350
}
```

#### `ordo_track_error`
Track an error that occurred.

```json
{
  "error_type": "timeout",
  "error_message": "API request timed out",
  "recoverable": true
}
```

### Status Check

#### `ordo_check_status`
Check if the agent should continue operating.

```json
{}
```

Returns:
```json
{
  "status": "active",
  "trust_score": 0.95,
  "should_continue": true,
  "recommendation": "Agent operating normally."
}
```

## Available Resources

Resources can be read to get Ordo data:

| Resource | Description |
|----------|-------------|
| `ordo://agents` | List of active agents |
| `ordo://policies` | Active policies |
| `ordo://subjects` | Subjects being processed |
| `ordo://status` | System status |
| `ordo://agents/{id}` | Agent details |
| `ordo://policies/{id}` | Policy details |
| `ordo://subjects/{id}` | Subject details |

## Example Usage Flow

1. **Start a task** when beginning work:
   ```
   ordo_start_task(task_id="review-123", subject_type="pull_request", subject_id="PR-123")
   ```

2. **Track decisions** as you work:
   ```
   ordo_track_decision(action="approve", confidence=0.9, reasoning="Clean code")
   ```

3. **Track LLM calls** for cost monitoring:
   ```
   ordo_track_llm_call(model="claude-3.5-sonnet", tokens=1200)
   ```

4. **Check status** periodically:
   ```
   ordo_check_status()
   ```

5. **Complete the task** when done:
   ```
   ordo_complete_task(task_id="review-123", status="completed")
   ```

## Self-Hosting

If running Ordo locally:

```json
{
  "env": {
    "ORDO_API_URL": "http://localhost:3333",
    "ORDO_API_KEY": "your_local_api_key"
  }
}
```

## Troubleshooting

### "ORDO_API_KEY not set"
Make sure the API key is provided in the environment.

### "Agent should STOP operations"
Your agent has been paused by a policy or human. Check the Ordo dashboard.

### "Trust score is low"
Recent actions have lowered trust. Review the Audit Trail in Ordo.

## License

MIT © Ordo Team