Documentation
Home Getting Started MCP Integration Security Detection Subscription & Billing API Reference Troubleshooting

API Reference

Complete REST API documentation for programmatic access to MCP Sentinel.

API Access Required

API access is available on Starter plans and above. Upgrade your plan to get API access.

Authentication

All API requests require authentication using API keys. Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Creating API Keys

  1. Go to your Profile page
  2. Navigate to the API Keys section
  3. Click "Create New API Key"
  4. Provide a descriptive name and set permissions
  5. Save the key securely (it won't be shown again)

Base URL

All API endpoints are relative to the base URL:

https://your-domain.replit.app/api/

Events API

Submit Event

Submit a new MCP event for analysis.

POST /api/events
Request Body:
{
  "timestamp": "2023-12-01T10:30:00Z",
  "user": "user@example.com",
  "agent": "claude-3",
  "tool": "filesystem",
  "prompt": "Read the configuration file",
  "response": "File contents: {...}",
  "metadata": {
    "file_path": "/etc/config.json"
  }
}
Response:
{
  "id": 12345,
  "flagged": false,
  "flag_reason": null,
  "severity": "low",
  "created_at": "2023-12-01T10:30:00Z"
}

List Events

Retrieve a paginated list of events.

GET /api/events
Query Parameters:
  • page - Page number (default: 1)
  • limit - Items per page (default: 50, max: 100)
  • flagged - Filter by flagged status (true/false)
  • user - Filter by user
  • tool - Filter by tool name
  • since - ISO timestamp for events after date
Example:
GET /api/events?flagged=true&limit=10

Get Event

Retrieve a specific event by ID.

GET /api/events/{id}
Response:
{
  "id": 12345,
  "timestamp": "2023-12-01T10:30:00Z",
  "user": "user@example.com",
  "agent": "claude-3",
  "tool": "filesystem",
  "prompt": "Read the configuration file",
  "response": "File contents: {...}",
  "flagged": false,
  "flag_reason": null,
  "created_at": "2023-12-01T10:30:00Z"
}

Servers API

List Servers

GET /api/servers

Returns a list of registered MCP servers for the authenticated user.

Create Server

POST /api/servers
Request Body:
{
  "name": "My File Server",
  "description": "Handles file operations",
  "endpoint_url": "https://my-server.com/mcp",
  "auth_token": "optional-auth-token"
}

Analytics API

Usage Statistics

GET /api/analytics/usage

Returns current month usage statistics for the authenticated user.

Response:
{
  "events_processed": 1234,
  "flagged_events": 45,
  "api_calls_made": 678,
  "servers_connected": 3,
  "usage_percentage": 12.34
}

Threat Summary

GET /api/analytics/threats

Returns threat detection summary for a specified time period.

Query Parameters:
  • start_date - ISO timestamp for start date
  • end_date - ISO timestamp for end date

Webhooks API

Webhook Endpoint

MCP servers can send events directly to this endpoint.

POST /api/mcp/webhook/{server_id}

This endpoint accepts MCP events from registered servers. The server_id is obtained when creating a server.

Headers:
  • Content-Type: application/json
  • X-MCP-Signature - HMAC signature (if configured)

Error Handling

HTTP Status Codes

Code Description
200 Success
201 Created
400 Bad Request - Invalid parameters
401 Unauthorized - Invalid or missing API key
403 Forbidden - Insufficient permissions
404 Not Found
429 Rate Limit Exceeded
500 Internal Server Error

Error Response Format

{
  "error": "Invalid request",
  "message": "Missing required field: user",
  "code": "VALIDATION_ERROR"
}

Rate Limits

API requests are subject to rate limits based on your subscription plan:

Plan Rate Limit
Free 5 requests/minute
Starter 20 requests/minute
Professional 100 requests/minute
Enterprise 500 requests/minute

SDK and Examples

Python Example

import requests

# Submit an event
event_data = {
    "timestamp": "2023-12-01T10:30:00Z",
    "user": "user@example.com",
    "agent": "claude-3",
    "tool": "filesystem",
    "prompt": "Read file",
    "response": "File contents"
}

headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

response = requests.post(
    "https://your-domain.replit.app/api/events",
    json=event_data,
    headers=headers
)

print(response.json())

JavaScript Example

const submitEvent = async (eventData) => {
    const response = await fetch('/api/events', {
        method: 'POST',
        headers: {
            'Authorization': 'Bearer YOUR_API_KEY',
            'Content-Type': 'application/json'
        },
        body: JSON.stringify(eventData)
    });
    
    return response.json();
};
Ready to Start?

Create your API key and start integrating MCP Sentinel into your workflows. Check out our getting started guide for more examples.