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

# MCP Protocol

> Native integration for AI agents

## What is MCP?

**Model Context Protocol (MCP)** is Anthropic's standard for AI agents to use tools. Instead of HTTP requests, AI agents communicate directly via stdio with JSON-RPC 2.0.

Syncline supports both REST API (HTTP) and MCP Protocol (stdio). Functionality is identical—choose what fits your architecture.

## Why Use MCP?

<CardGroup cols={2}>
  <Card title="Zero Latency" icon="bolt">
    No HTTP overhead. Direct process communication.
  </Card>

  <Card title="Native Integration" icon="plug">
    Works seamlessly with Claude and other MCP-compatible agents.
  </Card>

  <Card title="Stateful" icon="memory">
    Maintain context across multiple tool calls.
  </Card>

  <Card title="Simpler Auth" icon="key">
    No API keys in headers. Auth via environment variables.
  </Card>
</CardGroup>

## Architecture

```
┌─────────────────┐
│   AI Agent      │
│  (e.g., Claude) │
└────────┬────────┘
         │ stdio (JSON-RPC 2.0)
         │
┌────────▼────────┐
│ Syncline MCP    │
│     Server      │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  Google Calendar│
│    Firestore    │
└─────────────────┘
```

## Available Tools

<AccordionGroup>
  <Accordion title="find_mutual_availability" icon="calendar">
    Find time slots where attendees are available.

    **Input**:

    * `attendees`: Array of emails
    * `duration_minutes`: Meeting duration (optional)

    **Output**: 5 ranked time slots
  </Accordion>

  <Accordion title="schedule_meeting" icon="plus">
    Create a calendar event with Google Meet.

    **Input**:

    * `attendees`: Array of emails
    * `start_time`: ISO 8601 datetime
    * `title`: Meeting title
    * `duration_minutes`: Duration (optional)

    **Output**: Meeting details with Google Meet link
  </Accordion>

  <Accordion title="check_availability" icon="clock">
    Check a single user's calendar.

    **Input**:

    * `email`: User's email
    * `date_range`: Start and end times

    **Output**: Busy and free time slots
  </Accordion>

  <Accordion title="update_preferences" icon="sliders">
    Update user scheduling preferences.

    **Input**:

    * `email`: User's email
    * `preferences`: New preferences object

    **Output**: Updated preferences
  </Accordion>
</AccordionGroup>

## Integration Guides

<CardGroup cols={2}>
  <Card title="Claude Desktop" icon="robot" href="/mcp/claude-integration">
    Integrate with Claude Desktop or Claude Code
  </Card>

  <Card title="Python Client" icon="python" href="/mcp/python-client">
    Build custom Python agents
  </Card>

  <Card title="Node.js Client" icon="node-js" href="/mcp/nodejs-client">
    Build custom Node.js agents
  </Card>

  <Card title="Protocol Spec" icon="book" href="/mcp/protocol-spec">
    Full JSON-RPC 2.0 specification
  </Card>
</CardGroup>

## Quick Example

### 1. Start MCP Server

```bash theme={null}
# Download Syncline binary
# Set environment variables
export SERVER_MODE=mcp
export GCP_PROJECT_ID=your-project
export GOOGLE_CLIENT_ID=...
export GOOGLE_CLIENT_SECRET=...
export API_ENCRYPTION_KEY=...

# Start in MCP mode
./syncline
```

### 2. Send JSON-RPC Request

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}
```

### 3. Receive Response

```json theme={null}
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "find_mutual_availability",
        "description": "Find time slots where all attendees are available",
        "inputSchema": {
          "type": "object",
          "properties": {
            "attendees": {
              "type": "array",
              "items": {"type": "string", "format": "email"}
            }
          },
          "required": ["attendees"]
        }
      }
      // ... 3 more tools
    ]
  }
}
```

## MCP vs REST API

| Feature       | MCP Protocol | REST API         |
| ------------- | ------------ | ---------------- |
| **Transport** | stdio        | HTTP             |
| **Format**    | JSON-RPC 2.0 | REST JSON        |
| **Auth**      | Env vars     | API key header   |
| **Latency**   | \~1ms        | \~50ms           |
| **Streaming** | Yes          | No               |
| **Best For**  | AI agents    | Web apps, mobile |

## Protocol Flow

<Steps>
  <Step title="Initialize">
    Agent sends `initialize` method. Server responds with capabilities.
  </Step>

  <Step title="List Tools">
    Agent calls `tools/list`. Server returns available tools with schemas.
  </Step>

  <Step title="Call Tool">
    Agent calls `tools/call` with tool name and arguments. Server executes and returns result.
  </Step>

  <Step title="Repeat">
    Agent can call tools multiple times in same session.
  </Step>
</Steps>

## Example Conversation

<CodeGroup>
  ```json Initialize theme={null}
  // Agent → Server
  {
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {}
  }

  // Server → Agent
  {
    "jsonrpc": "2.0",
    "id": 1,
    "result": {
      "protocolVersion": "2024-11-05",
      "serverInfo": {"name": "syncline", "version": "1.0.0"},
      "capabilities": {"tools": {"listChanged": false}}
    }
  }
  ```

  ```json Find Availability theme={null}
  // Agent → Server
  {
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "find_mutual_availability",
      "arguments": {
        "attendees": ["alice@example.com", "bob@example.com"],
        "duration_minutes": 30
      }
    }
  }

  // Server → Agent
  {
    "jsonrpc": "2.0",
    "id": 2,
    "result": {
      "content": [
        {
          "type": "text",
          "text": "{\n  \"slots\": [...],\n  \"total_found\": 5\n}"
        }
      ]
    }
  }
  ```

  ```json Schedule Meeting theme={null}
  // Agent → Server
  {
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "schedule_meeting",
      "arguments": {
        "attendees": ["alice@example.com", "bob@example.com"],
        "start_time": "2025-11-20T10:00:00-08:00",
        "title": "Alice ↔ Bob Introduction",
        "duration_minutes": 30
      }
    }
  }

  // Server → Agent
  {
    "jsonrpc": "2.0",
    "id": 3,
    "result": {
      "content": [
        {
          "type": "text",
          "text": "{\n  \"meeting_id\": \"mtg_xyz\",\n  \"google_meet_link\": \"https://meet.google.com/...\"\n}"
        }
      ]
    }
  }
  ```
</CodeGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Integrate with Claude" href="/mcp/claude-integration">
    Add Syncline to Claude Desktop
  </Card>

  <Card title="Build Python Client" href="/mcp/python-client">
    Create custom Python agent
  </Card>
</CardGroup>