Make sure you’ve gone to https://app.observee.ai to obtain your API keys before starting!

​
MCP API Documentation

​
cURL Commands

​
1. Initialize MCP Server

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

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

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

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"
      }
    }
  }'

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

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. 
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: 
{
  "supportedServers": ["server1", "server2", "server3"]
}

​
2. Start Auth Flow (Basic)

Start an OAuth flow for a specific service without additional parameters. 
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. 
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. 
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. 
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

{
  "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

{
  "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