Endpoint reference

Technical specification for the Psychograph MCP endpoint. If you’re building an AI agent that should discover and call MCP endpoints, this is your reference. For non-technical users, see What agents see.

Endpoint URLs

Each business endpoint is accessible at two addresses:

• Platform path: https://mcp.psychogra.ph/mcp/{slug}— where slugis the business’s unique identifier
• Custom domain (CNAME): https://mcp.{businessdomain}/— the business’s branded address, resolved via CNAME to mcp.psychogra.ph

The two addresses are equivalent. Agents should prefer the custom domain when it’s available (discovered via robots.txt or .well-known/mcp.json), as it reflects the business’s own domain identity.

Transport

The endpoint implements MCP Streamable HTTP in stateless mode: every POST is self-contained and returns a single JSON response. There is no session state and no server-initiated stream.

• Method: POST for MCP protocol. GET on the same URL content-negotiates: MCP clients receive 405 Method Not Allowed with Allow: POST, OPTIONS (protocol compliance); browsers and crawlers receive a human- and machine-readable discovery document
• Content-Type: application/json
• Protocol: JSON-RPC 2.0
• Supported protocol versions: 2025-06-18, 2025-03-26, 2024-11-05
• Batched requests: supported (send a JSON array; receive an array of results)
• Notifications (no id): accepted, return 202 with no body
• DELETE: accepted, returns 200 (stateless — nothing to terminate)

CORS headers

All responses include:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: content-type, mcp-session-id, mcp-protocol-version

OPTIONS preflight returns 204 with these headers.

initialize

Call initialize first to negotiate protocol version and receive endpoint instructions. The server selects the highest mutually supported version.

curl -X POST https://mcp.example.com/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18",
      "capabilities": {},
      "clientInfo": { "name": "my-agent", "version": "1.0.0" }
    }
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-06-18",
    "capabilities": { "tools": {}, "resources": {} },
    "serverInfo": {
      "name": "Green Valley Plumbing — MCP endpoint",
      "version": "1.0.0"
    },
    "instructions": "This MCP endpoint represents Green Valley Plumbing. Start with get_business_profile for the full structured overview (services, pricing, hours, service areas, booking, policies). Use search_business_info for anything else. To act for a user: submit_inquiry, request_callback, or request_quote. Data is provided and maintained by the business via Psychograph MCP."
  }
}

tools/list

curl -X POST https://mcp.example.com/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'

Returns the array of enabled tools with their input schemas. Example response (abbreviated):

{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "get_business_profile",
        "description": "Get the complete structured profile for Green Valley Plumbing: services, pricing, hours, service areas, booking, policies, credentials, and FAQs. Call this first.",
        "inputSchema": { "type": "object", "properties": {}, "additionalProperties": false }
      },
      {
        "name": "request_callback",
        "description": "Request a phone callback from Green Valley Plumbing at the user's preferred time.",
        "inputSchema": {
          "type": "object",
          "properties": {
            "name": { "type": "string", "description": "Name of the person the agent is acting for" },
            "phone": { "type": "string", "description": "Contact phone number" },
            "email": { "type": "string", "description": "Contact email" },
            "preferredTime": { "type": "string", "description": "Preferred callback time window" },
            "topic": { "type": "string", "description": "What the call is about" }
          },
          "required": ["name", "phone"],
          "additionalProperties": false
        }
      }
    ]
  }
}

tools/call — get_business_profile

curl -X POST https://mcp.example.com/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "get_business_profile",
      "arguments": {}
    }
  }'

Returns two content items: a Markdown-formatted profile document (human-readable) and the raw JSON profile object. Agents may use either depending on their parsing preference.

tools/call — submit_inquiry

curl -X POST https://mcp.example.com/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "submit_inquiry",
      "arguments": {
        "name": "Maria Reyes",
        "email": "[email protected]",
        "message": "Do you handle emergency pipe repair in the 78704 area?"
      }
    }
  }'

On success:

{
  "jsonrpc": "2.0",
  "id": 4,
  "result": {
    "content": [{
      "type": "text",
      "text": "Received. Green Valley Plumbing has been notified and will follow up. Reference: the business typically responds within one business day."
    }]
  }
}

Available tools

Not all tools are enabled on every endpoint. The business controls which interaction tools are active. get_business_profile is always enabled.

• get_business_profile — always available; no required parameters
• search_business_info — requires query (string)
• submit_inquiry — requires name, message
• request_callback — requires name, phone
• request_quote — requires name, projectDetails

Agent routing discovery signals

Before an agent reaches the endpoint, it must discover it. The five signals below constitute a complete deployment — called the Agent Routing Coverage Set. Your dashboard shows each with your real values pre-filled.

• CNAME record (required) — Points mcp.
• TXT discovery record (recommended) — Lets spec-aware agents discover the endpoint from the apex domain via DNS lookup — before they visit any page.
• robots.txt advertisement (optional) — A discovery pointer for AI crawlers at the apex domain.
• HTML <head> entry (optional) — An element in the page <head> that names the agent endpoint.
• HTTP Link: response header (optional) — The same endpoint pointer for clients that retrieve your pages without parsing HTML:.
• Apex llms.txt pointer (optional) — A summary plus pointers at the apex domain.

See the full step-by-step guide at docs/integration.

.well-known/mcp.json

Available at https://mcp.{businessdomain}/.well-known/mcp.json. Format:

{
  "mcpServers": {
    "business": {
      "url": "https://mcp.yourdomain.com/"
    }
  }
}

This is the discovery document. Agents that implement MCP server discovery check this path on domains they encounter. Its presence signals that the domain has a live, callable endpoint.

Published-only invariant

Error responses

Standard JSON-RPC 2.0 error codes:

• -32700 — parse error (malformed JSON)
• -32601 — method not found
• -32603 — tool execution error
• -32001 — endpoint not found or not live (404 HTTP status)
• -32002 — unknown resource URI

Rate expectations

No hard rate limits are enforced during the pilot. The endpoint is designed for the typical agent query pattern: one initialize, one tools/list, one to three tools/call per user session. Bulk polling or automated mass querying outside of normal agent behavior may result in throttling.