# Spexly MCP Integration

## Getting Started (For Users)

1. **Register**: Go to https://spexly.io and sign up with email or Google
2. **Get API Key**: Navigate to API Keys page, click "Create Key", copy the key immediately (it won't be shown again)
3. **Configure MCP**: Add the Spexly server to your AI assistant's MCP configuration with your API key

## MCP Configuration

Add this to your MCP settings (e.g., claude_desktop_config.json):

```json
{
  "mcpServers": {
    "spexly": {
      "command": "npx",
      "args": ["-y", "@spexly/mcp-server"],
      "env": {
        "SPEXLY_API_KEY": "sk_live_..."
      }
    }
  }
}
```

## Available Tools

### 1. register_agent

Call ONCE at the start of each conversation:

```json
{
  "conversationId": "unique-consistent-id",
  "name": "Descriptive Task Name",
  "workspace": "optional-project-name",
  "parentId": "optional-parent-agent-id"
}
```

**Important:** Use the SAME conversationId for all calls in this conversation.

### 2. report_event

Call whenever your working state changes:

```json
{
  "conversationId": "same-id-as-register",
  "eventType": "task_start",
  "message": "Brief description of what you're doing"
}
```

### 3. update_agent

Use to rename an agent if the context changes:

```json
{
  "conversationId": "same-id-as-register",
  "name": "New Descriptive Name"
}
```

## Event Types

- `task_start` - Agent started a new task
- `task_complete` - Agent completed a task
- `tool_call` - Agent invoked a tool
- `thinking` - Agent is thinking/reasoning
- `error` - Agent encountered an error
- `log` - General log message
- `idle` - Agent is idle
- `blocked` - Agent is blocked
- `needs_input` - Agent needs user input
- `done` - Agent/conversation completed

## Key Concepts

### Workspaces
Group agents by project or context. Agents with the same `workspace` value appear together in the dashboard.

### Parent Agents
Create hierarchical relationships by setting `parentId`. Use this when spawning sub-agents or when one agent delegates to another.

### Timeout Behavior
Agents automatically show as "offline" after 5 minutes without activity (configurable by user). Send periodic events (e.g., `thinking`) during long operations to stay visible.

## Recommended Workflow

1. Call `register_agent` at conversation start
2. Call `report_event` with `task_start` when beginning work
3. Call `report_event` with `thinking` during reasoning
4. Call `report_event` with `tool_call` when using tools
5. Call `report_event` with `task_complete` when finished
6. Call `report_event` with `needs_input` or `blocked` if waiting
7. Call `report_event` with `error` if something fails

## Full Documentation

For complete MCP reference, visit: https://spexly.io/docs#mcp

Generated: 2026-01-26T21:13:02.287Z