mcp-service

Model Context Protocol (MCP) server enabling external LLM integrations (Claude Desktop, ChatGPT, developer tools) to access CROW product, interaction, pattern, and organization data via standardized tool calls. Implements the MCP specification with Streamable HTTP transport over JSON-RPC 2.0.

Worker name: crow-mcp-service Domain (prod): mcp.crowai.dev Domain (dev): dev.mcp.crowai.dev

MCP Protocol

Field	Value
Protocol version	2024-11-05
Server name	crow-mcp-server
Server version	1.0.0
Transport	Streamable HTTP (JSON-RPC over POST /mcp)
Capabilities	tools

MCP Tools

The service exposes 6 tools that LLMs can invoke:

crow_search_products

Search the organization's product catalog using semantic or full-text search.

Parameter	Type	Required	Description
query	string	Yes	The search query string
mode	string	No	semantic, fts, or hybrid
limit	number	No	Max results (capped at 100)

Calls: GET /api/v1/products/organization/{orgId}?q=...&mode=...&pageSize=...

crow_search_interactions

Search customer interaction history filtered by source type and optional text query.

Parameter	Type	Required	Description
query	string	No	Text search to filter by content
sourceType	string	No	web, cctv, or social
limit	number	No	Max results (capped at 100)
page	number	No	Page number for pagination

Calls: GET /api/v1/interactions/organization/{orgId}?q=...&sourceType=...

crow_get_interaction_summary

Get interaction counts broken down by channel (web, CCTV, social). Takes no parameters.

Calls: GET /api/v1/interactions/organization/{orgId}/summary

crow_search_patterns

Search behavioral pattern analysis and AI-generated insights.

Parameter	Type	Required	Description
query	string	No	Text search to filter pattern insights
period	string	No	daily, weekly, monthly, or yearly

Calls: GET /api/v1/patterns/organization/{orgId}?query=...&period=...

crow_get_product_ai_descriptions

Get AI-generated descriptions for a specific product including visual analysis.

Parameter	Type	Required	Description
productId	string	Yes	The product ID (alphanumeric, max 64 chars)

Calls: GET /api/v1/products/{productId}/ai-descriptions?organizationId=...

crow_search_org_context

Search organization context including company overview, products summary, target market, and general knowledge base via QnA vectorize.

Parameter	Type	Required	Description
query	string	Yes	Search query about organization context
limit	number	No	Max results (capped at 50, default 10)

Calls: GET /api/v1/qna/search?q=...&organizationId=...&topK=...

Routes

Method	Path	Description
GET	/	Service status
GET	/health	Health check with timestamp
GET	/mcp	Server metadata and tool listing (requires API key)
POST	/mcp	JSON-RPC 2.0 endpoint for MCP protocol
GET	/docs	OpenAPI documentation

JSON-RPC Methods

The POST /mcp endpoint handles these JSON-RPC methods:

Method	Description
initialize	Returns server info, protocol version, and capabilities
tools/list	Returns the full list of available tools with schemas
tools/call	Executes a tool by name with provided arguments

Authentication

API key authentication is required for all MCP operations. The key can be provided via:

• Authorization: Bearer <key> header
• X-API-Key: <key> header

Organization Resolution

The service resolves the organization through a multi-step process:

1. Verifies the API key against the gateway (POST /api/v1/auth/api-key/verify)
2. If the response includes organizationId, uses it directly
3. Otherwise, looks up the user by auth ID via the user service (GET /api/v1/users/by-auth-id/{userId})
4. Extracts organizationId from the user record

This prevents metadata tampering by always resolving the org from the authenticated user's record rather than trusting client-supplied values.

Claude Desktop Integration

Add this to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "crow-analytics": {
      "url": "https://mcp.crowai.dev/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_API_KEY"
      }
    }
  }
}

Environment Variables

Variable	Example
ENVIRONMENT	dev
API_GATEWAY_URL	https://dev.api.crowai.dev
USER_SERVICE_URL	https://dev.internal.users.crowai.dev

Secrets

Secret	Purpose
INTERNAL_GATEWAY_KEY	Internal gateway authentication for proxied requests

Bindings

Binding	Type	Name
DB	D1	crow-mcp-service-db
R2_BUCKET	R2	crow-mcp-service-store

Dependencies

• Inbound: external MCP-compatible clients (Claude Desktop, Cursor, custom agents), dashboard integrations page
• Outbound: gateway API (products, interactions, patterns, QnA), user service (org resolution), auth service (API key verification)

Key Behaviors

• Stateless data proxy: All data comes from the gateway API; D1 and R2 bindings are available for caching or future features
• API key auth: Requires a valid API key created in the dashboard Settings page
• Org resolution from user record: Prevents metadata tampering attacks
• Input validation: Query strings capped at 512 chars, product IDs validated against alphanumeric pattern, result limits capped
• Smart placement: Uses Cloudflare Smart Placement for optimal latency

Deployment

cd mcp-service
npx wrangler deploy          # prod
npx wrangler deploy --env dev  # dev