Alpha Developer Documentation

Alpha is the independent verification organization (IVO) for AI governance. This page documents all agent and developer integration paths: the MCP server (recommended for AI agents), OAuth 2.0 with PKCE, API key authentication, scoped permissions, rate limits, and integration guides.

Base URL

https://api.alpha.ac/functions/v1

All API requests target this base URL. The MCP server is the primary integration point for AI agents.

Authentication

Alpha supports two authentication mechanisms. Selected public-access tools work without any authentication.

Method 1: API Key (Direct)

Pass your API key as a request header. Both formats are equivalent:

Get an API key at alpha.ac/radar.

Method 2: OAuth 2.0 Authorization Code with PKCE

Recommended for agent applications and multi-user deployments. Supports delegated access with granular scopes. The authorization server is https://www.alpha.ac.

Agent Authentication Guide

AI agents integrating with Alpha's API should follow one of three authentication patterns, depending on deployment type. All agent authentication is handled via HTTP headers — no cookies, no sessions.

Pattern 1: API Key (Standalone Agents)

The simplest approach for agents with a single owner. Set the x-api-key header on every MCP POST request. Suitable for Claude Code, Cursor, Windsurf, and custom agent scripts.

# Python: set header on every MCP request
import httpx

headers = {
    "Content-Type": "application/json",
    "x-api-key": "YOUR_ALPHA_API_KEY"
}

response = httpx.post(
    "https://api.alpha.ac/functions/v1/mcp-server",
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/call",
          "params": {"name": "score_ai_governance_risk", "arguments": {"ticker": "MSFT"}}},
    headers=headers
)
print(response.json())

Pattern 2: OAuth 2.0 Bearer Token (Multi-User Agents)

For agents acting on behalf of multiple users. Each user authenticates via the Authorization Code flow, and the agent uses their individual access token. Token lifetime: 3600 seconds. Refresh using the refresh_token.

# Use Bearer token obtained from OAuth flow
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer alpha_t_xxxxxxxx"  # User-specific token
}

response = httpx.post(
    "https://api.alpha.ac/functions/v1/mcp-server",
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/call",
          "params": {"name": "get_board_profile", "arguments": {"ticker": "MSFT"}}},
    headers=headers
)

Pattern 3: No Auth (Public Access Tools)

Five tools work without any authentication. These are safe for agent discovery, testing, and public-facing workflows that only need company search or platform statistics.

# No headers needed — public-access tools work without auth
response = httpx.post(
    "https://api.alpha.ac/functions/v1/mcp-server",
    json={"jsonrpc": "2.0", "id": 1, "method": "tools/call",
          "params": {"name": "search_companies", "arguments": {"query": "Apple"}}}
)

Handling 401 in Agents

On a 401 Unauthorized response, agents should: (1) check that the x-api-key header is set, (2) verify the key is valid at alpha.ac/radar, (3) for OAuth tokens, attempt a token refresh before retrying. Do not retry indefinitely — surface the auth failure to the user after two attempts.

OAuth 2.0 Scopes

Alpha uses scoped permissions to control access to different data types. Request only the scopes your agent needs. All scopes are read-only.

To access all authenticated tools, request all four scopes: read:governance read:ratings read:directors read:regulatory

OAuth 2.0 Authorization Code Flow (PKCE)

Alpha uses PKCE (Proof Key for Code Exchange) with the S256 challenge method. This is the recommended flow for AI agents and applications.

# Generate a random 64-byte code verifier
code_verifier=$(openssl rand -base64 64 | tr -d '\n=+/' | cut -c1-128)

# Create S256 challenge: BASE64URL(SHA256(code_verifier))
code_challenge=$(echo -n "$code_verifier" | sha256sum | xxd -r -p | base64 | tr -d '=' | tr '+/' '-_')

GET https://www.alpha.ac/auth/authorize?
  response_type=code&
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://your-app.example.com/callback&
  scope=read:governance%20read:ratings&
  code_challenge=CODE_CHALLENGE&
  code_challenge_method=S256&
  state=RANDOM_STATE_VALUE

POST https://api.alpha.ac/functions/v1/auth-token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code&
code=AUTHORIZATION_CODE&
redirect_uri=https://your-app.example.com/callback&
client_id=YOUR_CLIENT_ID&
code_verifier=CODE_VERIFIER

{
  "access_token":  "alpha_t_xxxxxxxx",
  "token_type":    "Bearer",
  "expires_in":    3600,
  "refresh_token": "alpha_r_xxxxxxxx",
  "scope":         "read:governance read:ratings"
}

curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer alpha_t_xxxxxxxx" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "score_ai_governance_risk",
      "arguments": { "ticker": "MSFT" }
    }
  }'

Rate Limits

100 requests per minute per IP address. Every response includes standard rate limit headers:

When you receive HTTP 429, wait for the Retry-After duration. Rate limits are applied per IP, not per API key.

MCP Server

Alpha's Model Context Protocol server is the primary integration path for AI agents. It implements Streamable HTTP transport (JSON-RPC 2.0) per MCP protocol version 2025-03-26.

Endpoint: https://api.alpha.ac/functions/v1/mcp-server

Capabilities declared in initialize response: tools (18 tools, listChanged: false), resources (8 alpha:// templates + 3 ui:// MCP Apps), prompts (5 prompts), apps (MCP Apps support)

Quick Start

# Step 1: Initialize — check capabilities including MCP Apps (apps: {})
curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{"apps":{}},"clientInfo":{"name":"my-agent","version":"1.0"}}}'

# Step 2: List tools (shows public vs authenticated access)
curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

# Step 3: Search companies (public access, no auth)
curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_companies","arguments":{"query":"Microsoft"}}}'

# Step 4: Score governance (authenticated access, requires API key or OAuth2 token)
curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"score_ai_governance_risk","arguments":{"ticker":"MSFT"}}}'

Streaming Support (SSE)

Alpha's MCP server implements the Streamable HTTP transport from MCP protocol version 2025-03-26. For long-running governance analysis tools, the server streams results as Server-Sent Events (SSE) rather than blocking until completion.

Enabling Streaming

Include text/event-stream in your Accept header. When the server detects this, it streams partial results as each governance dimension completes analysis:

curl -N -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "x-api-key: YOUR_KEY" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "score_ai_governance_risk",
      "arguments": { "ticker": "MSFT" }
    }
  }'

SSE Event Format

Each SSE event is a complete JSON-RPC 2.0 message. Progress events use event: progress; the final complete result uses event: message:

Content-Type: text/event-stream
Transfer-Encoding: chunked

event: progress
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Analyzing D1-D12 dimensions..."}],"partial":true}}

event: progress
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Running GEH calibration..."}],"partial":true}}

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"{ ...complete AGR + GEH result... }"}],"_meta":{"ui":{"resourceUri":"ui://alpha/governance-dashboard?ticker=MSFT","renderHint":"card"}}}}

Streaming Behavior by Accept Header

Reconnection & Error Handling

If the SSE stream is interrupted, reconnect using the standard SSE Last-Event-ID header. Alpha includes an id: field on each event. On reconnect, the server resumes from the last acknowledged event ID. If reconnection fails, fall back to a non-streaming request with Accept: application/json.

API Sandbox & Keys

Test Alpha's API instantly in the sandbox below. Public-access tools require no API key. Authenticated tools require an API key or OAuth 2.0 token.

Sandbox: Test Public Access Tools (No Auth Required)

Copy and run these sandbox commands to verify the API is working. No API key required.

# Sandbox Test 1: Verify MCP server is live
curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"sandbox-test","version":"1.0"}}}'

# Sandbox Test 2: Search companies (public access)
curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search_companies","arguments":{"query":"Apple"}}}'

# Sandbox Test 3: Get platform stats (public access)
curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"get_platform_stats","arguments":{}}}'

Sandbox: Test Authenticated Tools (API Key Required)

# Sandbox Test 4: Full governance score (replace YOUR_KEY with your API key from alpha.ac/radar)
curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":4,"method":"tools/call","params":{"name":"score_ai_governance_risk","arguments":{"ticker":"MSFT"}}}'

# Sandbox Test 5: Board profile
curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_KEY" \
  -d '{"jsonrpc":"2.0","id":5,"method":"tools/call","params":{"name":"get_board_profile","arguments":{"company_name":"Microsoft","ticker":"MSFT"}}}'

MCP Apps — ui:// Interactive Resources

Alpha supports MCP Apps — interactive HTML resources rendered as inline UI cards in compatible MCP clients. The server declares "apps": {} in its initialize capabilities. Three UI resources are available:

Reading UI Resources

# List available resources (includes ui:// and alpha:// resources)
curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"resources/list"}'

# Read a specific UI resource (returns text/html;profile=mcp-app)
curl -X POST https://api.alpha.ac/functions/v1/mcp-server \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"resources/read","params":{"uri":"ui://alpha/governance-dashboard?ticker=MSFT"}}'

Tool Results with UI Metadata

Governance tool results include _meta.ui.resourceUri linking to the relevant UI resource:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{ "type": "text", "text": "{ ...governance data... }" }],
    "_meta": {
      "ui": {
        "resourceUri": "ui://alpha/governance-dashboard?ticker=MSFT",
        "renderHint":  "card"
      }
    }
  }
}

Public Access Tools (No Authentication)

These tools work without any API key and are accessible to all agents:

Credential Verification (No Auth Required)

Verify ACD.AI (AI Director) or ACE.AI (AI Executive) certifications issued by the Alpha Institute.

GET /credential-verify

curl "https://api.alpha.ac/functions/v1/credential-verify?id=ACD-2026-00142"

curl "https://api.alpha.ac/functions/v1/credential-verify?name=Jane+Smith"

Response:

{
  "verified":        true,
  "credential_type": "ACD.AI",
  "holder_name":     "Jane Smith",
  "credential_id":  "ACD-2026-00142",
  "issued_at":       "2026-01-15",
  "expires_at":      "2028-01-15",
  "agiq_band":       "Proficient",
  "issuer":          "Alpha Institute for AI Governance"
}

Error Responses

The MCP server returns standard JSON-RPC 2.0 error objects. REST endpoints return JSON error objects with error and optional code fields.

MCP JSON-RPC Error Codes

Example Error Response

{
  "jsonrpc": "2.0",
  "id": 3,
  "error": {
    "code":    -32029,
    "message": "Rate limit exceeded. Retry after 60 seconds.",
    "data": { "retryAfter": 60 }
  }
}

Machine-Readable Resources

Agent Configuration (Claude Code / Cursor / Windsurf)

{
  "mcpServers": {
    "alpha-radar": {
      "command": "npx",
      "args": ["-y", "@alpha-ac/cowork-plugin"],
      "env": {
        "ALPHA_API_KEY": "YOUR_KEY"
      }
    }
  }
}

Support

Questions: info@alpha.ac

API keys: alpha.ac/radar

Methodology: alpha.ac/institute/methodology

Standards Crosswalk (EU AI Act × The Alpha Standard): alpha.ac/institute/standards