Skip to content

API.md

Latest commit

 

History

History
644 lines (525 loc) · 11.6 KB

API.md

File metadata and controls

644 lines (525 loc) · 11.6 KB
Raw

API Documentation

This document provides comprehensive API documentation for the MCP FastAPI server with authentication.

Base URL

http://localhost:8000

Authentication

Most endpoints require authentication using JWT tokens. Include the token in the Authorization header:

Authorization: Bearer YOUR_JWT_TOKEN_HERE

Response Format

All API responses follow this structure:

Success Response

{
  "data": "response_data",
  "status": "success"
}

Error Response

{
  "error": "Error Type",
  "message": "Detailed error message",
  "status_code": 400
}

Endpoints

Core Endpoints

Health Check

GET /health

Description: Check server health status
Authentication: Not required
Response:

{
  "status": "healthy",
  "timestamp": 1609459200.0,
  "service": "MCP FastAPI Template",
  "version": "0.1.0"
}

Server Information

GET /

Description: Get comprehensive server information
Authentication: Not required
Response:

{
  "service": "MCP FastAPI Template",
  "version": "0.1.0",
  "description": "A production-ready MCP server template",
  "mcp_server": {
    "name": "mcp-fastapi-template",
    "version": "0.1.0",
    "capabilities": {
      "tools": true,
      "resources": true,
      "prompts": true,
      "logging": true
    }
  },
  "endpoints": {
    "health": "/health",
    "metrics": "/metrics",
    "auth": "/api/v1/auth",
    "mcp": "/api/v1/mcp",
    "docs": "/docs",
    "redoc": "/redoc"
  },
  "authentication": {
    "enabled": true,
    "login_endpoint": "/api/v1/auth/login",
    "register_endpoint": "/api/v1/auth/register"
  }
}

Metrics

GET /metrics

Description: Prometheus metrics endpoint
Authentication: Configurable (default: not required)
Response: Prometheus format metrics

Authentication API (/api/v1/auth)

Login

POST /api/v1/auth/login

Description: Authenticate user and receive JWT token
Authentication: Not required

Request Body:

{
  "username": "admin",
  "password": "admin123"
}

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 1800
}

Error Responses:

  • 401 Unauthorized: Invalid credentials
  • 401 Unauthorized: Account disabled

Register

POST /api/v1/auth/register

Description: Register a new user account
Authentication: Not required

Request Body:

{
  "username": "newuser",
  "email": "user@example.com",
  "password": "securepassword",
  "role": "user"
}

Response:

{
  "message": "User registered successfully",
  "user_id": "3",
  "username": "newuser"
}

Error Responses:

  • 400 Bad Request: Username already exists
  • 400 Bad Request: Email already exists
  • 400 Bad Request: Invalid role

Get Current User

GET /api/v1/auth/me

Description: Get current authenticated user information
Authentication: Required

Response:

{
  "user_id": "1",
  "username": "admin",
  "email": "admin@example.com",
  "role": "admin"
}

Get User Permissions

GET /api/v1/auth/permissions

Description: Get current user's role and permissions
Authentication: Required

Response:

{
  "user_id": "1",
  "username": "admin",
  "role": "admin",
  "permissions": [
    "read", "write", "delete", "admin",
    "tools:execute", "tools:list",
    "resources:read", "resources:write",
    "prompts:read", "prompts:write"
  ]
}

Refresh Token

POST /api/v1/auth/refresh

Description: Refresh JWT access token
Authentication: Required (current valid token)

Request Headers:

Authorization: Bearer CURRENT_TOKEN

Response:

{
  "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "token_type": "bearer",
  "expires_in": 1800
}

Logout

POST /api/v1/auth/logout

Description: Logout current user (token blacklisting)
Authentication: Required

Response:

{
  "message": "Successfully logged out"
}

MCP API (/api/v1/mcp)

All MCP endpoints require authentication when authentication is enabled.

MCP Health Check

GET /api/v1/mcp/health

Description: MCP-specific health check with uptime
Authentication: Required

Response:

{
  "status": "healthy",
  "timestamp": "2024-01-01T12:00:00Z",
  "version": "0.1.0",
  "uptime": 3600.5
}

MCP Server Info

GET /api/v1/mcp/info

Description: Get MCP server information
Authentication: Required

Response:

{
  "name": "mcp-fastapi-template",
  "version": "0.1.0",
  "capabilities": {
    "tools": true,
    "resources": true,
    "prompts": true,
    "logging": true
  }
}

MCP Protocol Endpoint

POST /api/v1/mcp/

Description: Main MCP protocol endpoint
Authentication: Required
Permission: read

Request Body (example initialize):

{
  "method": "initialize",
  "id": "req-1"
}

Response:

{
  "id": "req-1",
  "result": {
    "serverInfo": {
      "name": "mcp-fastapi-template",
      "version": "0.1.0"
    },
    "capabilities": {
      "tools": true,
      "resources": true,
      "prompts": true,
      "logging": true
    }
  }
}

Tools API

List Tools

GET /api/v1/mcp/tools

Description: Get list of available MCP tools
Authentication: Required
Permission: tools:list

Response:

{
  "tools": [
    {
      "name": "echo",
      "description": "Echo back the provided message",
      "input_schema": {
        "type": "object",
        "properties": {
          "message": {
            "type": "string",
            "description": "The message to echo back"
          }
        },
        "required": ["message"]
      }
    },
    {
      "name": "get_current_time",
      "description": "Get the current UTC time",
      "input_schema": {
        "type": "object",
        "properties": {},
        "required": []
      }
    }
  ]
}

Execute Tool

POST /api/v1/mcp/tools/{tool_name}/call

Description: Execute a specific MCP tool
Authentication: Required
Permission: tools:execute

URL Parameters:

  • tool_name (string): Name of the tool to execute

Request Body (echo example):

{
  "message": "Hello, World!"
}

Response:

{
  "result": ["Echo: Hello, World!"]
}

Request Body (get_current_time example):

{}

Response:

{
  "result": ["Current UTC time: 2024-01-01T12:00:00Z"]
}

Error Responses:

  • 404 Not Found: Tool not found
  • 400 Bad Request: Invalid arguments

Resources API

List Resources

GET /api/v1/mcp/resources

Description: Get list of available MCP resources
Authentication: Required
Permission: resources:read

Response:

{
  "resources": [
    {
      "name": "server_info",
      "description": "Information about the MCP server",
      "uri": "server://info"
    }
  ]
}

Get Resource

GET /api/v1/mcp/resources/{resource_name}

Description: Get specific MCP resource content
Authentication: Required
Permission: resources:read

URL Parameters:

  • resource_name (string): Name of the resource

Response:

{
  "contents": [
    {
      "uri": "server://info",
      "mimeType": "application/json",
      "text": "{\"server\": \"mcp-fastapi-template\", \"version\": \"0.1.0\"}"
    }
  ]
}

Prompts API

List Prompts

GET /api/v1/mcp/prompts

Description: Get list of available MCP prompts
Authentication: Required
Permission: prompts:read

Response:

{
  "prompts": [
    {
      "name": "greeting",
      "description": "Generate a personalized greeting",
      "arguments": [
        {
          "name": "name",
          "description": "Name of the person to greet",
          "required": true
        }
      ]
    }
  ]
}

Generate Prompt

POST /api/v1/mcp/prompts/{prompt_name}/generate

Description: Generate content for a specific prompt
Authentication: Required
Permission: prompts:read

URL Parameters:

  • prompt_name (string): Name of the prompt

Request Body:

{
  "name": "Alice"
}

Response:

{
  "prompt": "Hello, Alice! Welcome to the MCP FastAPI server."
}

Roles and Permissions

Available Roles

Role Description Default Permissions
guest Basic read-only access read, tools:list
user Standard user access read, write, tools:execute, tools:list, resources:read, prompts:read
moderator Extended access with deletion rights All user permissions + delete, resources:write, prompts:write
admin Full system access All permissions including admin

Available Permissions

Permission Description
read Basic read access
write Write/modify access
delete Delete access
admin Administrative functions
tools:list List available tools
tools:execute Execute tools
resources:read Read resources
resources:write Write/modify resources
prompts:read Read prompts
prompts:write Write/modify prompts

Error Codes

Status Code Description Common Causes
400 Bad Request Invalid input, malformed JSON
401 Unauthorized Missing/invalid token, expired token
403 Forbidden Insufficient permissions
404 Not Found Resource/endpoint not found
429 Too Many Requests Rate limit exceeded
500 Internal Server Error Server error, check logs

Rate Limiting

The API implements rate limiting with the following defaults:

  • Rate: 100 requests per minute per IP
  • Headers: Rate limit information in response headers
    • X-RateLimit-Remaining: Requests remaining
    • X-RateLimit-Reset: Reset timestamp

Configuration:

RATE_LIMIT_REQUESTS_PER_MINUTE=100

Example Workflows

Complete Authentication Flow

# 1. Login
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

# Extract token from response
export TOKEN="your-jwt-token-here"

# 2. Get user info
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/auth/me

# 3. List tools
curl -H "Authorization: Bearer $TOKEN" \
  http://localhost:8000/api/v1/mcp/tools

# 4. Execute tool
curl -X POST http://localhost:8000/api/v1/mcp/tools/echo/call \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"message": "Hello API!"}'

# 5. Logout
curl -X POST http://localhost:8000/api/v1/auth/logout \
  -H "Authorization: Bearer $TOKEN"

Role-based Access Testing

# Test as different users
# Admin user (full access)
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "admin", "password": "admin123"}'

# Regular user (limited access)  
curl -X POST http://localhost:8000/api/v1/auth/login \
  -H "Content-Type: application/json" \
  -d '{"username": "user", "password": "user123"}'

Interactive Documentation

When the server is running, visit these URLs for interactive API documentation:

These interfaces allow you to test all endpoints directly in your browser with proper authentication.