API Documentation

The MCPSafe REST API provides programmatic access to the MCP server directory, security reports, and submission system.

Authentication

The API is currently open and does not require authentication. API keys will be available in a future release for higher rate limits and write access.

Base URL

https://mcpsafe.dev/api/v1

Endpoints

GET/api/v1/servers

Search and list MCP servers with filtering and pagination.

Query Parameters

Parameter	Type	Description
q	string	Full-text search query
category	string	Filter by category slug (e.g. "database", "ai-ml")
transport	string	Filter by transport type: "stdio" or "streamable-http"
min_security	string	Minimum security tier: S, A, B, C, D, or F
sort	string	Sort order: "security", "popularity", "updated", or "name"
limit	integer	Results per page (default: 20, max: 100)
offset	integer	Pagination offset (default: 0)

Example

curl "https://mcpsafe.dev/api/v1/servers?q=database&category=database&sort=security&limit=10"

# Response
{
  "servers": [
    {
      "id": "...",
      "slug": "postgres-mcp",
      "name": "PostgreSQL MCP Server",
      "security_tier": "A",
      "security_score": 85.2,
      "tool_count": 5,
      ...
    }
  ],
  "total": 42,
  "limit": 10,
  "offset": 0
}

GET/api/v1/servers/:slug

Get full details for a single MCP server, including the latest security scan.

Example

curl "https://mcpsafe.dev/api/v1/servers/postgres-mcp"

# Response
{
  "server": {
    "id": "...",
    "slug": "postgres-mcp",
    "name": "PostgreSQL MCP Server",
    "description": "...",
    "tools": [...],
    "security_tier": "A",
    "security_score": 85.2,
    ...
  },
  "security_scan": {
    "overall_score": 85.2,
    "tier": "A",
    "description_score": 90,
    "permission_score": 80,
    "findings": [...]
  }
}

GET/api/v1/servers/:slug/security

Get the latest security scan report for a server.

Example

curl "https://mcpsafe.dev/api/v1/servers/postgres-mcp/security"

# Response
{
  "scan": {
    "id": "...",
    "overall_score": 85.2,
    "tier": "A",
    "description_score": 90,
    "permission_score": 80,
    "behavior_score": 85,
    "stability_score": 88,
    "findings": [
      {
        "severity": "medium",
        "category": "excessive-scope",
        "title": "Broad filesystem access",
        "description": "..."
      }
    ],
    "completed_at": "2026-03-10T12:00:00Z"
  }
}

GET/api/v1/categories

List all categories with server counts, sorted by most popular.

Example

curl "https://mcpsafe.dev/api/v1/categories"

# Response
{
  "categories": [
    {
      "id": "...",
      "slug": "database",
      "name": "Database",
      "description": "Database access, queries, and management tools",
      "server_count": 25
    },
    ...
  ]
}

POST/api/v1/submissions

Submit a new MCP server for review and inclusion in the directory.

Request Body

Parameter	Type	Description
type*	string	"npm", "github", "pypi", or "url"
url*	string	Package name, repository URL, or server URL
email	string	Contact email for review notifications

Example

curl -X POST "https://mcpsafe.dev/api/v1/submissions" \
  -H "Content-Type: application/json" \
  -d '{"type": "npm", "url": "@example/mcp-server", "email": "dev@example.com"}'

# Response (201 Created)
{
  "submission_id": "...",
  "status": "pending"
}

MCP Endpoint

MCPSafe itself is an MCP server. Connect any MCP client to search the directory directly from your AI tools.

// Claude Desktop config
{
  "mcpServers": {
    "mcpsafe": {
      "type": "streamable-http",
      "url": "https://mcpsafe.dev/mcp"
    }
  }
}

// Cursor config
{
  "mcpServers": {
    "mcpsafe": {
      "url": "https://mcpsafe.dev/mcp"
    }
  }
}

Code Examples

Python

import requests

# Search for database servers
response = requests.get("https://mcpsafe.dev/api/v1/servers", params={
    "q": "database",
    "sort": "security",
    "limit": 5
})
data = response.json()

for server in data["servers"]:
    print(f"{server['name']} - Security: {server['security_tier']} ({server['security_score']})")

JavaScript / Node.js

const response = await fetch(
  "https://mcpsafe.dev/api/v1/servers?q=database&sort=security&limit=5"
);
const { servers, total } = await response.json();

console.log(`Found ${total} servers`);
servers.forEach(s => {
  console.log(`${s.name} - Security: ${s.security_tier} (${s.security_score})`);
});

curl

# Search servers
curl -s "https://mcpsafe.dev/api/v1/servers?q=filesystem&limit=5" | jq '.servers[] | {name, security_tier, tool_count}'

# Get server details
curl -s "https://mcpsafe.dev/api/v1/servers/filesystem-mcp" | jq '.server'

# Get security report
curl -s "https://mcpsafe.dev/api/v1/servers/filesystem-mcp/security" | jq '.scan.findings'

# Submit a server
curl -X POST "https://mcpsafe.dev/api/v1/submissions" \
  -H "Content-Type: application/json" \
  -d '{"type":"github","url":"https://github.com/user/mcp-server"}'