Connect AI with MCP

Give any compatible AI client a tenant-scoped WinLayer toolset through one remote Streamable HTTP endpoint.

Connection endpoint: open Developer Portal → Connect AI to copy the API origin configured for your workspace deployment. The route is always /api/v1/mcp.

What this is

WinLayer's MCP server is a real adapter over the same public API, grounded agents, tenant checks, plan limits, and approval services used by the web, desktop, CLI, and mobile clients. It does not create a second data store or bypass product governance.

The API key fixes the tenant, environment, owner, and available scopes before any tool is listed.
Each MCP request is rate limited and metered under that API key.
Sandbox keys expose deterministic synthetic read tools and never advertise live AI or action tools.
Live AI runs still enforce subscription capability, usage allowance, hourly cost cap, evidence grounding, and the workspace kill switch.
Action decisions still require a live actions:write key and the key owner's current workspace role.

Connect in three steps

Create a dedicated key under Developer Portal → Credentials. Choose only the scopes that client needs.
Add a remote MCP server in the AI client, choose HTTP or Streamable HTTP, and paste the endpoint shown in the portal.
Configure Authorization: Bearer <key> using the client's credential store. Never commit the plaintext key.

json

{
  "mcpServers": {
    "winlayer": {
      "type": "http",
      "url": "https://YOUR_API_ORIGIN/api/v1/mcp",
      "headers": {
        "Authorization": "Bearer ${WINLAYER_API_KEY}"
      }
    }
  }
}

Configuration names differ between clients. The endpoint, Streamable HTTP transport, and bearer header are the portable parts.

Tool catalog

Scope	Tools exposed when granted
`workspace:read`	winlayer_workspace
`opportunities:read`	winlayer_search_opportunities, winlayer_get_opportunity
`pipeline:read`	winlayer_list_pipeline
`signals:read`	winlayer_list_signals
`forecasts:read`	winlayer_list_forecasts
`contacts:read`	winlayer_list_contacts
`agencies:read`	winlayer_list_agencies
`relationships:read`	winlayer_list_relationships
`intelligence:read`	winlayer_list_intelligence
`agents:read`	winlayer_list_agents and, for live keys, winlayer_list_actions
`agents:run`	winlayer_ask, winlayer_run_agent — live keys only
`actions:write`	winlayer_approve_action, winlayer_reject_action — live keys only
`usage:read`	winlayer_usage

Protocol check

This request verifies authentication and the MCP handshake without running a business tool:

bash

curl -sS "https://YOUR_API_ORIGIN/api/v1/mcp" \
  -H "Authorization: Bearer $WINLAYER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  --data '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "capabilities": {},
      "clientInfo": { "name": "connection-check", "version": "1.0.0" }
    }
  }'

Security boundaries

Use one key per AI client so usage, rotation, and revocation stay attributable.
Start with a sandbox key to inspect schemas and output without exposing production workspace data.
Do not grant actions:write to a client that only needs research or Q&A.
Revoking the key removes the MCP client's access immediately; there is no separate MCP session credential.
A client can request only tools that appear in its scoped catalog. Server callbacks enforce the same scope again before calling WinLayer services.

Continue with API authentication and scopes, security and tenancy, and roles and permissions.