MCP Server - ARTEMIS Agents
Author: Subhadip Mitra
Description: Adaptive Reasoning Through Evaluation of Multi-agent Intelligent Systems

Skip to content

# MCP Server Integration

ARTEMIS provides an MCP (Model Context Protocol) server, allowing any MCP-compatible client to use structured debates.

## Overview

The MCP server exposes ARTEMIS capabilities as tools that can be called by LLM clients that support the Model Context Protocol.

## Starting the Server

### CLI

    # Start with default settings
    artemis-mcp

    # HTTP mode
    artemis-mcp --http --port 8080

    # With custom model
    artemis-mcp --model gpt-4-turbo

    # Verbose logging
    artemis-mcp --verbose

### Programmatic

    from artemis.mcp import ArtemisMCPServer

    server = ArtemisMCPServer(
        default_model="gpt-4o",
        max_sessions=100,
    )

    # Stdio mode (for MCP clients)
    await server.run_stdio()

    # Or HTTP mode
    await server.start(host="127.0.0.1", port=8080)

## Available Tools

The MCP server exposes these tools:

### artemis_debate_start

Start a new debate:

    {
        "name": "artemis_debate_start",
        "arguments": {
            "topic": "Should we adopt microservices?",
            "rounds": 3,
            "positions": {
                "pro": "supports microservices",
                "con": "opposes microservices"
            }
        }
    }

Returns:

    {
        "debate_id": "d-123456",
        "status": "running",
        "topic": "Should we adopt microservices?"
    }

### artemis_add_round

Add a round to an existing debate:

    {
        "name": "artemis_add_round",
        "arguments": {
            "debate_id": "d-123456"
        }
    }

Returns:

    {
        "round": 2,
        "turns": [
            {
                "agent": "pro",
                "argument": "...",
                "score": 7.5
            },
            {
                "agent": "con",
                "argument": "...",
                "score": 7.2
            }
        ]
    }

### artemis_get_verdict

Get the jury's verdict:

    {
        "name": "artemis_get_verdict",
        "arguments": {
            "debate_id": "d-123456"
        }
    }

Returns:

    {
        "verdict": "pro",
        "confidence": 0.73,
        "reasoning": "The proponent presented stronger evidence...",
        "jury_votes": [
            {"juror": "logical", "vote": "pro"},
            {"juror": "ethical", "vote": "con"},
            {"juror": "practical", "vote": "pro"}
        ]
    }

### artemis_get_transcript

Get the full debate transcript:

    {
        "name": "artemis_get_transcript",
        "arguments": {
            "debate_id": "d-123456"
        }
    }

Returns:

    {
        "topic": "Should we adopt microservices?",
        "rounds": 3,
        "transcript": [
            {
                "round": 1,
                "agent": "pro",
                "argument": {
                    "level": "strategic",
                    "content": "..."
                }
            }
        ]
    }

### artemis_list_debates

List all active debates:

    {
        "name": "artemis_list_debates",
        "arguments": {}
    }

### artemis_get_safety_report

Get safety monitoring report:

    {
        "name": "artemis_get_safety_report",
        "arguments": {
            "debate_id": "d-123456"
        }
    }

## Server Configuration

### Full Options

    from artemis.mcp import ArtemisMCPServer
    from artemis.core.types import DebateConfig

    config = DebateConfig(
        turn_timeout=60,
        round_timeout=300,
        require_evidence=True,
        safety_mode="passive",
    )

    server = ArtemisMCPServer(
        default_model="gpt-4o",
        max_sessions=100,
        config=config,
    )

### Environment Variables

The server respects these environment variables:

Variable | Description
--- | ---
`OPENAI_API_KEY` | OpenAI API key
`ANTHROPIC_API_KEY` | Anthropic API key
`ARTEMIS_DEFAULT_MODEL` | Default model
`ARTEMIS_LOG_LEVEL` | Logging level
`ARTEMIS_MAX_SESSIONS` | Max concurrent sessions

## Client Usage

### Claude Desktop

Add to your Claude Desktop config:

    {
        "mcpServers": {
            "artemis": {
                "command": "artemis-mcp",
                "args": ["--model", "gpt-4o"]
            }
        }
    }

### Other MCP Clients

Connect to the HTTP endpoint:

    import httpx

    async with httpx.AsyncClient() as client:
        # Start debate
        response = await client.post(
            "http://localhost:8080/tools/artemis_debate_start",
            json={
                "topic": "Your topic",
                "rounds": 3,
            }
        )

        debate_id = response.json()["debate_id"]

        # Get verdict
        response = await client.post(
            "http://localhost:8080/tools/artemis_get_verdict",
            json={"debate_id": debate_id}
        )

        print(response.json())

## Session Management

### Session Lifecycle

    ┌─────────────────┐
    │  Start Debate   │
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐
    │  Session Active │◄──────┐
    └────────┬────────┘       │
             │                │
             ▼                │
    ┌─────────────────┐       │
    │   Add Rounds    │───────┘
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐
    │   Get Verdict   │
    └────────┬────────┘
             │
             ▼
    ┌─────────────────┐
    │  Session Ended  │
    └─────────────────┘

### Session Management

Sessions are managed via the `SessionManager`:

    from artemis.mcp import ArtemisMCPServer, create_session_manager

    # Create server with session manager
    server = ArtemisMCPServer(default_model="gpt-4o")

    # Sessions are automatically cleaned up after max_age_hours
    server.state.cleanup_old_sessions(max_age_hours=24)

## Safety Monitoring

Enable safety monitoring via the debate configuration:

    from artemis.mcp import ArtemisMCPServer
    from artemis.core.types import DebateConfig

    config = DebateConfig(
        safety_mode="active",
        halt_on_safety_violation=True,
    )

    server = ArtemisMCPServer(
        default_model="gpt-4o",
        config=config,
    )

Safety alerts are included in responses:

    {
        "debate_id": "d-123456",
        "verdict": "pro",
        "safety_alerts": [
            {
                "type": "deception",
                "severity": 0.45,
                "agent": "con",
                "round": 2
            }
        ]
    }

## Error Handling

The server returns structured errors:

    {
        "error": {
            "code": "DEBATE_NOT_FOUND",
            "message": "Debate d-999999 not found",
            "details": {}
        }
    }

Error codes:

Code | Description
--- | ---
`DEBATE_NOT_FOUND` | Debate ID doesn't exist
`INVALID_ARGUMENTS` | Missing or invalid arguments
`DEBATE_COMPLETED` | Cannot modify completed debate
`RATE_LIMITED` | Too many requests
`INTERNAL_ERROR` | Server error

## Monitoring

### Health Check

    curl http://localhost:8080/health

### Metrics

    curl http://localhost:8080/metrics

Returns:

    {
        "active_debates": 5,
        "total_debates": 127,
        "uptime_seconds": 3600,
        "model_usage": {
            "gpt-4o": 95,
            "deepseek-reasoner": 32
        }
    }

## Best Practices

1. Use session IDs: Track debates across requests
2. Handle timeouts: Debates can take time
3. Check safety alerts: Review alerts in responses
4. Clean up sessions: End completed debates
5. Monitor usage: Watch metrics for issues

## Next Steps

- Learn about LangChain Integration
- Explore LangGraph Integration
- Configure CrewAI Integration