API Documentation — CraftedTrust REST API

Authentication

Most read endpoints are public and require no authentication. Write endpoints (scan, certify) are rate-limited by IP.

For higher rate limits, include an API key in the X-API-Key header:

curl -H "X-API-Key: your_api_key_here" \ https://mcp.craftedtrust.com/api/v1/stats

🔮 Coming Soon

Prepaid Balance (x402): AI agents will be able to pay per-request using the x402 HTTP payment protocol. No API key needed — just a funded wallet.

Rate Limits

Tier	Limit	Window
Free (no key)	5 scans / hour per IP	1 hour
Free (no key)	100 reads / hour per IP	1 hour
API Key	1,000 requests / hour	1 hour

Rate-limited responses return 429 Too Many Requests with a Retry-After header.

Base URL

https://mcp.craftedtrust.com/api/v1

Get ecosystem-wide statistics: total servers, certified count, average trust score, and featured server lists.

Response

{ "stats": { "totalServers": 1259, "certifiedServers": 12, "avgTrustScore": 75, "recentlyFlagged": 3 }, "recentlyScanned": [...], "highestRated": [...], "recentlyFlagged": [...] }

Search the server registry by name, URL, or publisher.

Query Parameters

Param	Type	Description
q	string	Search query (required)
sort	string	Sort order: relevance, score-high, score-low, recent, name
page	number	Page number (default: 1)

Example

curl "https://mcp.craftedtrust.com/api/v1/search?q=github&sort=score-high"

Get trust score summary for a specific server by its URL (URL-encoded).

curl "https://mcp.craftedtrust.com/api/v1/server/https%3A%2F%2Fmcp.example.com"

Response

{ "url": "https://mcp.example.com", "name": "Example MCP Server", "trustScore": 82, "trustLabel": "trusted", "transportType": "http", "lastScanned": "2026-03-11T14:00:00Z", "scanCount": 5, "publisherName": "Example Inc.", "certificationStatus": "none" }

Get the full scan report including factor breakdown, discovered tools/resources, network behavior, and findings.

curl "https://mcp.craftedtrust.com/api/v1/server/https%3A%2F%2Fmcp.example.com/report"

Get an SVG trust badge for embedding in READMEs, websites, or marketplaces.

curl "https://mcp.craftedtrust.com/api/v1/server/https%3A%2F%2Fmcp.example.com/badge"

Returns: image/svg+xml. See the Badge Generator for embed code.

Request a trust scan of an MCP server. The scan runs synchronously and returns the result. Rate limited to 5/hour per IP.

Request Body

curl -X POST https://mcp.craftedtrust.com/api/v1/scan \ -H "Content-Type: application/json" \ -d '{"server_url": "https://mcp.example.com/mcp"}'

Response

{ "trustScore": 78, "trustLabel": "moderate", "discovery": { "toolCount": 5, "resourceCount": 2 }, "factors": { "declarationAccuracy": 16, "permissionMinimality": 12, "networkBehavior": 15, "codeTransparency": 5, "publisherReputation": 8, "transportSecurity": 10, "threatMatch": 12 }, "findings": [...] }

Submit a server for certification. Requires publisher info and Stripe payment for Standard/Premium tiers.

curl -X POST https://mcp.craftedtrust.com/api/v1/certify \ -H "Content-Type: application/json" \ -d '{ "server_url": "https://mcp.example.com/mcp", "publisher_name": "Example Inc.", "publisher_email": "[email protected]", "tier": "standard" }'

Response Codes

Code	Meaning
200	Success
400	Bad request — invalid parameters
404	Server not found in registry
429	Rate limit exceeded
500	Internal server error

Trust Score Breakdown

The trust score (0-100) is computed from seven independently weighted factors:

Factor	Max Points	Description
declarationAccuracy	20	Does the server honestly declare tools, resources, and permissions?
permissionMinimality	15	Does it request only the permissions it needs?
networkBehavior	20	Are outbound connections declared and minimal?
codeTransparency	10	Is the code open-source or audited?
publisherReputation	10	Is the publisher a known, reputable entity?
transportSecurity	10	Does it use HTTPS with modern TLS?
threatMatch	15	Does it avoid known malicious patterns?

Score Tiers

Range	Label	Meaning
80–100	Trusted	Safe to use — minimal risk
60–79	Moderate	Generally safe — review findings
40–59	Caution	Proceed with care — notable concerns
20–39	Warning	Significant risks identified
0–19	Dangerous	Critical threats — do not connect

MCP Server Interface Phase 2

CraftedTrust will expose its own MCP server interface, allowing AI agents to query trust scores and scan results using the MCP protocol directly — no REST API needed.

🚧 This feature is under active development and will be available in Phase 2.

Agent Payment (x402) Phase 2

AI agents will be able to pay for API access using the x402 HTTP payment protocol. Each request is paid for individually from a prepaid balance — no API key management, no subscription overhead.

🚧 This feature is under active development and will be available in Phase 2.