API Reference

Complete reference for OpenMCP HTTP API and Python client

Table of Contents

Authentication

OpenMCP uses API key authentication. Include your API key in the Authorization header: 

curl -H "Authorization: Bearer your-api-key" \
     http://localhost:9000/api/v1/health

Getting API Keys: Use openmcp init-config to generate a default API key, or openmcp create-key <name> to create additional keys.

Browser Sessions

Create Browser Session

Endpoint: POST /api/v1/browseruse/create_session
Returns: Session ID

Request Body:

{
  "headless": true,
  "timeout": 30,
  "window_size": {
    "width": 1920,
    "height": 1080
  }
}

Response:

{
  "session_id": "session_abc123",
  "status": "created"
}

cURL Example:

curl -X POST \
  -H "Authorization: Bearer your-api-key" \
  -H "Content-Type: application/json" \
  -d '{"headless": true, "timeout": 30}' \
  http://localhost:9000/api/v1/browseruse/create_session

List Active Sessions

Endpoint: GET /api/v1/browseruse/sessions
Returns: List of active sessions

Response:

{
  "sessions": [
    {
      "session_id": "session_abc123",
      "created_at": "2024-01-01T12:00:00Z",
      "status": "active"
    }
  ]
}

Close Browser Session

Endpoint: POST /api/v1/browseruse/close_session
Returns: Confirmation

Request Body:

{
  "session_id": "session_abc123"
}

Element Interaction

Find Elements

Endpoint: POST /api/v1/browseruse/find_elements
Returns: List of matching elements

Request Body:

{
  "session_id": "session_abc123",
  "selector": "#submit-button",
  "by": "css",
  "timeout": 10
}

Selector Types:

  • css - CSS selector (default)
  • xpath - XPath expression
  • id - Element ID
  • name - Element name attribute
  • class - CSS class name
  • tag - HTML tag name

Click Element

Endpoint: POST /api/v1/browseruse/click_element
Returns: Click result

Request Body:

{
  "session_id": "session_abc123",
  "selector": "button[type='submit']",
  "by": "css",
  "wait_for_element": true,
  "timeout": 10
}

Type Text

Endpoint: POST /api/v1/browseruse/type_text
Returns: Typing result

Request Body:

{
  "session_id": "session_abc123",
  "selector": "input[name='username']",
  "text": "john_doe",
  "clear_first": true,
  "by": "css"
}

Screenshots

Take Screenshot

Endpoint: POST /api/v1/browseruse/take_screenshot
Returns: Base64 encoded image

Request Body:

{
  "session_id": "session_abc123",
  "full_page": false,
  "element_selector": null,
  "format": "png"
}

Parameters:

  • session_id - Browser session ID (required)
  • full_page - Capture full page or viewport only (optional, default: false)
  • element_selector - CSS selector to capture specific element (optional)
  • format - Image format: "png" or "jpeg" (optional, default: "png")

Response:

{
  "screenshot": "iVBORw0KGgoAAAANSUhEUgAA...",
  "format": "png",
  "size": {
    "width": 1920,
    "height": 1080
  }
}

Python Client

OpenMCP provides a simple Python client that wraps the HTTP API for easy integration.

Basic Usage 

import openmcp
import asyncio

async def main():
    # Simple browser automation
    async with openmcp.browser() as browser:
        await browser.navigate("https://example.com")
        await browser.click("#submit-button")
        await browser.type("input[name='search']", "OpenMCP")
        await browser.screenshot("result.png")

asyncio.run(main())

MCP Client 

import openmcp

# Initialize client with API key
mcp = openmcp.MCP("browseruse", api_key="your-api-key")

# Create a session
session = await mcp.create_session(headless=True)

# Use the session
await session.navigate("https://example.com")
elements = await session.find_elements("a")
await session.close()

Browser Context Manager 

import openmcp

# Context manager automatically handles session lifecycle
async with openmcp.browser(headless=False) as browser:
    # Navigate to page
    await browser.navigate("https://github.com/login")
    
    # Fill login form
    await browser.type("input[name='login']", "username")
    await browser.type("input[name='password']", "password")
    await browser.click("input[type='submit']")
    
    # Wait for navigation
    await browser.wait_for_url("https://github.com/")
    
    # Take screenshot
    screenshot_data = await browser.screenshot()
    
# Session automatically closed when exiting context

Utility Functions 

import openmcp

# One-liner screenshot
await openmcp.screenshot("https://example.com", "example.png")

# Test form filling
await openmcp.test_form("https://httpbin.org/forms/post", {
    "custname": "John Doe",
    "custtel": "555-1234",
    "custemail": "john@example.com"
})

# Ensure server is running
if await openmcp.ensure_server_running():
    print("OpenMCP server is ready!")
else:
    print("Please start OpenMCP server first")

Error Handling

HTTP API Errors 

{
  "error": "ElementNotFound",
  "message": "Element with selector '#missing-element' not found",
  "details": {
    "selector": "#missing-element",
    "timeout": 10
  }
}

Common Error Codes:

  • 400 - Bad Request (invalid parameters)
  • 401 - Unauthorized (invalid API key)
  • 404 - Not Found (session or element not found)
  • 408 - Request Timeout (operation timed out)
  • 500 - Internal Server Error

Python Client Error Handling 

import openmcp
from openmcp import MCPError

try:
    async with openmcp.browser() as browser:
        await browser.navigate("https://example.com")
        await browser.click("#missing-button")
        
except MCPError as e:
    print(f"OpenMCP Error: {e}")
    print(f"Error type: {e.error_type}")
    print(f"Details: {e.details}")
    
except Exception as e:
    print(f"Unexpected error: {e}")

Rate Limits & Best Practices

Default Limits

  • Max Sessions: 5 concurrent browser sessions per API key
  • Session Timeout: 30 minutes of inactivity
  • Operation Timeout: 30 seconds per operation

Best Practices

  • Always close sessions when done to free up resources
  • Use context managers in Python for automatic cleanup
  • Set appropriate timeouts for your use case
  • Handle errors gracefully and retry when appropriate
  • Use headless mode for better performance in production