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

# Connecting to Our MCP Server using HTTP

> For those who want to use our API directly, please see this tutorial

<Info>
  Make sure you've gone to [https://app.observee.ai](https://app.observee.ai) to obtain your API keys before starting!
</Info>

## MCP API Documentation

## cURL Commands

### 1. Initialize MCP Server

```bash theme={null}
curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 0,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": {
        "name": "observee-chat-client",
        "version": "1.0.0"
      }
    }
  }'
```

**Response Headers:**

* `mcp-session-id: <generated-session-id>`
* `content-type: text/event-stream`

### 2. Send Initialized Notification

```bash theme={null}
curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'mcp-session-id: SESSION_ID_FROM_INITIALIZE_RESPONSE' \
  --header 'mcp-protocol-version: 2025-06-18' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'
```

### 3. List Tools

```bash theme={null}
curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'mcp-session-id: SESSION_ID_FROM_INITIALIZE_RESPONSE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'
```

### 4. Call Tool

```bash theme={null}
curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'mcp-session-id: SESSION_ID_FROM_INITIALIZE_RESPONSE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "TOOL_NAME_FROM_TOOLS_LIST",
      "arguments": {
        "param1": "value1",
        "param2": "value2"
      }
    }
  }'
```

#### Example: Gmail Search

```bash theme={null}
curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'mcp-session-id: SESSION_ID_FROM_INITIALIZE_RESPONSE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "Gmail__search_emails",
      "arguments": {
        "query": "from:user@example.com",
        "maxResults": 2
      }
    }
  }'
```

#### Example: Everything Calculator

```bash theme={null}
curl -X POST 'https://mcp.observee.ai/mcp' \
  --header 'Authorization: Bearer YOUR_API_KEY_HERE' \
  --header 'mcp-session-id: SESSION_ID_FROM_INITIALIZE_RESPONSE' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json, text/event-stream' \
  --data '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "Everything__add",
      "arguments": {
        "a": 5,
        "b": 2
      }
    }
  }'
```

> **💡 Finding Tool Arguments:** Use the `/tools/list` endpoint first to get each tool's `inputSchema`. This schema defines the required and optional arguments for each tool, including their types, descriptions, and validation rules.

## Key Implementation Notes

### Authentication

* Uses Bearer token authentication with Observee API key
* Format: `Authorization: Bearer YOUR_API_KEY_HERE`

### Session Management

1. **Initialize** returns `mcp-session-id` in response headers
2. **Subsequent requests** must include this session ID as a header
3. Session IDs are UUIDs (e.g., `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)

### Response Types

* **Initialize**: Returns `text/event-stream` (SSE) for real-time updates
* **Notifications**: Returns `202 Accepted` with empty body
* **Tool operations**: Return `application/json` with structured data

## McpAuth API - cURL Commands

### 1. Get Available Servers

Get a list of all supported authentication servers.

```bash theme={null}
curl -X POST 'https://mcpauth.observee.ai/supported_servers' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "OBSERVEE_API_KEY": "YOUR_API_KEY_HERE"
  }'
```

**Expected Response:**

```json theme={null}
{
  "supportedServers": ["server1", "server2", "server3"]
}
```

### 2. Start Auth Flow (Basic)

Start an OAuth flow for a specific service without additional parameters.

```bash theme={null}
curl -X POST 'https://mcpauth.observee.ai/enterprise/<server>/start' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "OBSERVEE_API_KEY": "YOUR_API_KEY_HERE"
  }'
```

### 3. Start Auth Flow (with Client ID)

Start an OAuth flow with a specific client ID passed as query parameter.

```bash theme={null}
curl -X POST 'https://mcpauth.observee.ai/enterprise/<server>/start?client_id=YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "OBSERVEE_API_KEY": "YOUR_API_KEY_HERE"
  }'
```

### 4. Start Auth Flow (with Custom Redirect URL)

Start an OAuth flow with a custom redirect URL.

```bash theme={null}
curl -X POST 'https://mcpauth.observee.ai/enterprise/<server>/start' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "OBSERVEE_API_KEY": "YOUR_API_KEY_HERE",
    "CUSTOM_REDIRECT_URL": "https://your-app.com/auth/callback"
  }'
```

### 5. Start Auth Flow (with Additional Parameters)

Start an OAuth flow with custom parameters for specific auth servers.

```bash theme={null}
curl -X POST 'https://mcpauth.observee.ai/enterprise/<server>/start?client_id=YOUR_CLIENT_ID' \
  --header 'Content-Type: application/json' \
  --header 'Accept: application/json' \
  --data '{
    "OBSERVEE_API_KEY": "YOUR_API_KEY_HERE",
    "CUSTOM_REDIRECT_URL": "https://your-app.com/auth/callback",
    "scopes": "custom-scope-here",
    "workspace": "your-workspace"
  }'
```

### Server Discovery

Replace `<server>` in the auth flow URLs with any server name from the `supportedServers` array returned by the `/supported_servers` endpoint above.

### Expected Auth Flow Response

```json theme={null}
{
  "auth_url": "https://accounts.google.com/oauth/authorize?client_id=...",
  "state": "random-state-string",
  "expires_in": 3600,
  "callback_url": "https://mcpauth.observee.ai/callback"
}
```

### Error Response Example

```json theme={null}
{
  "error": "Invalid API key",
  "status": 401
}
```

### Usage Flow

1. **Get available servers** to see what services are supported
2. **Start auth flow** for your desired service
3. **Redirect user** to the `auth_url` from the response
4. **Handle callback** when user completes OAuth flow
5. **Use the authenticated credentials** in your MCP tools

### Notes

* All requests use `POST` method
* API key is always required in the request body as `OBSERVEE_API_KEY`
* Client ID is optional and passed as query parameter
* Custom parameters go in the request body
* The auth flow returns a URL where users complete OAuth authentication