clara-mcp-server

crazi-co/clara-mcp-server

3.1

If you are the rightful owner of clara-mcp-server and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to dayong@mcphub.com.

The Clara MCP Server is a Model Context Protocol server that provides AI agents with access to Clara's backend APIs, enabling them to verify online content and analyze information efficiently.

Tools
5
Resources
0
Prompts
0

Clara MCP Server

1. Overview

This is an MCP (Model Context Protocol) server that exposes Clara backend APIs as tools for AI agents.

Clara provides fast, reliable tools to check online content, verify claims, analyze posts and videos, and understand what's true or false across the internet - all in one place.

The MCP server enables AI agents to interact with Clara's APIs through a standardized tool interface, making it easy to integrate Clara's capabilities into agent workflows.

2. Quick Start

2.1 Installation

  1. Clone the repository:

    git clone https://github.com/crazi-co/clara-mcp-server.git
cd clara-mcp-server

  2. Install dependencies:

    pip install -r requirements.txt

  3. Set up environment variables:

    • Copy .env.example to .env
    • Fill in your credentials: 
      USER_ID=your_user_id
API_KEY_TOKEN=your_api_key_token
PORT=8000

    Note: You can either set USER_ID and API_KEY_TOKEN in the .env file, or pass them from your AI agent via headers:

    • Authorization: Bearer <api_key_token>
    • User-Id: <user_id>

  4. Run the MCP server:

    python run.py

The server will start on the port specified in your .env file (default: 8000).

3. Stack & Core Components

3.1 Technology Stack

  • Language: Python
  • MCP Framework: FastMCP
  • Web Framework: Starlette (for SSE endpoint)
  • HTTP Client: requests (with session management and retry strategy)
  • Server: Uvicorn

3.2 Architecture

  1. MCP Server (FastMCP)

    • Exposes Clara API endpoints as MCP tools
    • Provides SSE (Server-Sent Events) stream for agent communication
    • Handles tool registration and execution

  2. Tool Layer

    • Organized into modules: user, transaction, task, agent, stripe, misc
    • Each tool maps to a Clara API endpoint
    • Tools handle request formatting and response parsing

  3. Request Utility

    • Centralized HTTP client with session management
    • Automatic retry strategy for transient errors
    • Error logging for unexpected exceptions

  4. Authentication Middleware

    • Validates Bearer token from Authorization header
    • Extracts User-Id from headers
    • Returns 401 for missing or invalid credentials

4. Authentication & Authorization

4.1 API Key Authentication

  • Header: Authorization: Bearer <api-key-token>
  • User ID Header: User-Id: <user-id>

Both headers are required for authenticated requests.

4.2 Request Flow

  1. Client sends request with Authorization and User-Id headers
  2. Middleware validates:
    • Authorization header must start with "Bearer "
    • Both user_id and api_key_token must be present
  3. If validation fails → returns 401 Unauthorized
  4. If valid → request proceeds to MCP server

5. Available Tools

The MCP server exposes the following Clara API endpoints as tools:

5.1 User Tools (user.*)

  • user.view
    • View user account details
    • Returns: user information including credits, email, preferences, etc.

5.2 Transaction Tools (transaction.*)

  • transaction.view_all

    • View all user transactions with pagination
    • Parameters: limit (int), offset (int)
    • Returns: array of transaction objects

  • transaction.view

    • View a specific transaction
    • Parameters: transaction_id (string)
    • Returns: transaction details

5.3 Task Tools (task.*)

  • task.view_all

    • View all user tasks with pagination
    • Parameters: limit (string), offset (string)
    • Returns: array of task objects

  • task.view

    • View a specific task
    • Parameters: task_id (string)
    • Returns: task details including status and result

5.4 Agent Tools (agent.*)

  • agent.analyze_transaction
    • Analyze a transaction on Base using Analytiq's agent
    • Minimum credits required: 10
    • Parameters: transaction_hash (string)
    • Returns: task object (analysis runs asynchronously)

5.5 Stripe Tools (stripe.*)

  • stripe.rate

    • Get current credit rate and pricing
    • Returns: rate information with limits and credits per dollar

  • stripe.portal

    • Create Stripe customer portal session for billing management
    • Returns: portal URL

  • stripe.buy

    • Buy credits via Stripe checkout
    • Parameters: amount (int), return_path (string)
    • Returns: checkout session URL

5.6 Misc Tools (misc.*)

  • misc.health

    • Check API health status
    • Returns: service status information

  • misc.version

    • Get API version
    • Returns: current API version

6. Configuration

6.1 Environment Variables

  • USER_ID: Default user ID (can be overridden by User-Id header)
  • API_KEY_TOKEN: Default API key token (can be overridden by Authorization header)
  • PORT: Server port (default: 8000)
  • BASE_URL: Clara API base URL (default: http://localhost:5001/api/v1)

7. API Response Handling

7.1 Response Format

All tools return JSON responses in the following format:

{
  "data": {...},
  "message": "Success message",
  "status": "success"
}

7.2 Error Handling

  • API Errors (4xx, 5xx): Returned as-is in the response (not treated as exceptions)
  • Network/Connection Errors: Logged and re-raised as exceptions
  • Authentication Errors: Returned as 401 HTTP responses by middleware

7.3 Retry Strategy

The request utility includes automatic retry for:

  • Status codes: 429, 502, 503, 504
  • Max retries: 3
  • Backoff factor: 1

Note: 500 errors are not retried as they represent valid API responses.

8. MCP Protocol

8.1 Endpoints

  • GET /sse: Server-Sent Events stream for agent communication
  • POST /messages: MCP message endpoint

8.2 Tool Naming Convention

Tools are named using dot notation: <module>.<action>

Examples:

  • user.view
  • transaction.view_all
  • stripe.buy

9. Development

9.1 Project Structure

.
├── app/
│   ├── data/           # Global data and configuration
│   ├── tools/          # MCP tool implementations
│   │   ├── user.py
│   │   ├── transaction.py
│   │   ├── task.py
│   │   ├── agent.py
│   │   ├── stripe.py
│   │   └── misc.py
│   └── utils/          # Utility functions
│       └── request.py   # HTTP request helper
├── run.py              # Server entry point
└── requirements.txt    # Python dependencies

9.2 Adding New Tools

  1. Create or update the appropriate tool file in app/tools/
  2. Define a static method with the @app.data.mcp.tool(name = "module.action") decorator
  3. Use make_request() from app.utils.request for HTTP calls
  4. Include proper type hints and docstrings

Example:

@staticmethod
@app.data.mcp.tool(name = "module.action")
def action(param: str) -> Dict[str, Any]:
    """Tool description."""
    return make_request(
        method = "GET",
        url = f"{app.data.base_url}/endpoint",
        headers = app.data.headers
    )

10. Summary

This MCP server provides a standardized interface for AI agents to interact with Clara's APIs. It:

  • Exposes Clara endpoints as MCP tools
  • Handles authentication and authorization
  • Provides robust error handling and retry logic
  • Maintains session management for efficient HTTP requests
  • Supports SSE for real-time agent communication

The server is designed to be:

  • Stateless: Each request is self-contained
  • Extensible: Easy to add new tools by implementing Clara API endpoints
  • Reliable: Automatic retries and comprehensive error handling