Skip to content

MCP Tools API

!!! info "TL;DR" JSON-RPC endpoint for AI agents. Execute MCP tools to manage surveys, query responses, trigger workflows. Requires agent API key authentication.

Execute Tool

Call an MCP tool via JSON-RPC.

POST /api/mcp/tools

Authentication: Required (agent API key)

Request Format:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "create_survey",
    "arguments": {
      "title": "Q1 Product Feedback",
      "questions": [...]
    }
  }
}

Response Format (Success):

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "survey_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "draft",
    "url": "https://canviq.app/surveys/550e8400-e29b-41d4-a716-446655440000"
  }
}

Response Format (Error):

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32602,
    "message": "Invalid params",
    "data": {
      "validation_errors": ["questions must be an array"]
    }
  }
}

List Available Tools

Get all available MCP tools and their schemas.

POST /api/mcp/tools

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/list"
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "tools": [
      {
        "name": "create_survey",
        "description": "Create a new survey with questions",
        "inputSchema": {
          "type": "object",
          "properties": {
            "title": {"type": "string"},
            "questions": {"type": "array"}
          },
          "required": ["title", "questions"]
        }
      },
      {
        "name": "list_surveys",
        "description": "Get all surveys with filters",
        "inputSchema": {...}
      }
    ]
  }
}

Natural Language Tool Call

Use natural language instead of structured JSON.

POST /api/mcp/tools

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "mode": "natural_language",
    "input": "Create a 5-question NPS survey targeting users who signed up in the last 30 days"
  }
}

The server parses the natural language input, generates the appropriate tool call, and executes it.

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "parsed_tool": "create_survey",
    "parsed_params": {
      "title": "New User Onboarding Experience",
      "questions": [...],
      "targeting": {
        "user_segment": "created_at > now() - interval '30 days'"
      }
    },
    "execution_result": {
      "survey_id": "uuid",
      "status": "draft"
    }
  }
}

Stream Tool Execution

For long-running operations, use SSE streaming.

Step 1: Initiate execution

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "analyze_sentiment",
    "arguments": { "survey_id": "uuid" },
    "stream": true
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "stream_url": "https://canviq.app/api/mcp/stream/550e8400-e29b-41d4-a716-446655440000"
  }
}

Step 2: Connect to SSE stream

curl -N https://canviq.app/api/mcp/stream/550e8400-e29b-41d4-a716-446655440000 \
  -H "Authorization: Bearer agent-api-key"

SSE Events:

event: progress
data: {"step": "fetching_responses", "percent": 20}

event: progress
data: {"step": "analyzing_sentiment", "percent": 60}

event: result
data: {"overall_sentiment": 0.65, "positive_count": 90, "negative_count": 20}

event: done
data: {"success": true}

Subscribe to Events

Subscribe to realtime events (e.g., new survey responses).

POST /api/mcp/subscribe

Request:

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "subscribe",
  "params": {
    "events": ["survey.response.created"],
    "filters": {
      "survey_id": "550e8400-e29b-41d4-a716-446655440000"
    }
  }
}

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "subscription_id": "uuid",
    "stream_url": "https://canviq.app/api/mcp/subscribe/uuid"
  }
}

Connect to the stream_url to receive SSE events as they occur.

Error Codes

JSON-RPC error codes used by the MCP server:

Code Meaning Description
-32700 Parse error Invalid JSON
-32600 Invalid request Malformed JSON-RPC
-32601 Method not found Unknown method
-32602 Invalid params Validation failed
-32603 Internal error Server error
-32000 Authentication failed Invalid API key
-32001 Authorization failed Insufficient scopes
-32002 Rate limit exceeded Too many requests

Authentication

Include the agent API key in the Authorization header:

curl -X POST https://canviq.app/api/mcp/tools \
  -H "Authorization: Bearer your-agent-api-key" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", ...}'

The server verifies:

  1. API key is valid and not expired
  2. Agent has required scopes for the tool
  3. Agent hasn't exceeded rate limits

If any check fails, the request is rejected with an appropriate error code.

Rate Limiting

Rate limits are enforced per agent. See the Rate Limits page for details.

Rate limit headers are included in every response:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 45
X-RateLimit-Reset: 1675123456

Example: Create Survey

Full example of creating a survey via the MCP API:

curl -X POST https://canviq.app/api/mcp/tools \
  -H "Authorization: Bearer sk_agent_abc123" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "create_survey",
      "arguments": {
        "title": "Q1 Product Feedback",
        "description": "Help us improve",
        "questions": [
          {
            "type": "nps",
            "text": "How likely are you to recommend us?",
            "required": true
          },
          {
            "type": "text",
            "text": "What can we improve?",
            "required": false
          }
        ],
        "settings": {
          "allow_multiple_responses": false
        }
      }
    }
  }'

Response:

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "survey_id": "550e8400-e29b-41d4-a716-446655440000",
    "status": "draft",
    "url": "https://canviq.app/surveys/550e8400-e29b-41d4-a716-446655440000"
  }
}

What's Next