Skip to content

README.md

Latest commit

 

History

History
381 lines (315 loc) · 9.52 KB

README.md

File metadata and controls

381 lines (315 loc) · 9.52 KB

MCP Tools API Documentation

The MCP Tools API provides AI tools for web search, web scraping, and code execution.

Quick Start

Examples: API examples index includes discovery and call samples.

URLs

Authentication

All endpoints require authentication through the Kong gateway.

For complete authentication documentation, see Authentication Guide

Quick example:

# Get guest token
TOKEN=$(curl -s -X POST http://localhost:8000/llm/auth/guest-login | jq -r '.access_token')

# Use in requests
curl -H "Authorization: Bearer $TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list"}' \
 http://localhost:8000/v1/mcp

Available Tools

  • google_search - Serper/SearXNG-backed web search with optional filters and location hints
  • scrape - Fetch and parse a web page, optionally returning Markdown
  • file_search_index / file_search_query - Lightweight vector store to index custom text and run similarity queries
  • python_exec - Execute trusted code through SandboxFusion (optional approval flag)
  • External providers - Additional tools declared in services/mcp-tools/mcp-providers.md are loaded automatically

How It Works

All tools use JSON-RPC 2.0 protocol. You send a request with tool name and parameters, get back results.

Need help with the protocol? See MCP Tools Protocol Guide for request format and error handling patterns.

Service Ports & Configuration

Component Port Key Environment Variables
HTTP Server 8091 MCP_TOOLS_HTTP_PORT
Search Providers 443 SERPER_API_KEY, MCP_SEARCH_ENGINE, SEARXNG_URL
Vector Store 3015 VECTOR_STORE_URL
SandboxFusion 8080 SANDBOXFUSION_URL, MCP_SANDBOX_REQUIRE_APPROVAL

Required Environment Variables

MCP_TOOLS_HTTP_PORT=8091
SERPER_API_KEY=your_serper_api_key
MCP_SEARCH_ENGINE=serper             # serper | searxng | offline
SEARXNG_URL=http://searxng:8080      # used when MCP_SEARCH_ENGINE=searxng
VECTOR_STORE_URL=http://vector-store-mcp:3015
SANDBOXFUSION_URL=http://sandbox-fusion:8080
OTEL_ENABLED=false

# Auth (optional)
AUTH_ENABLED=true
AUTH_ISSUER=http://localhost:8085/realms/jan
ACCOUNT=account
AUTH_JWKS_URL=http://keycloak:8085/realms/jan/protocol/openid-connect/certs

Optional Configuration

MCP_TOOLS_LOG_LEVEL=info
MCP_TOOLS_LOG_FORMAT=json          # json | console
SANDBOXFUSION_TIMEOUT=30s
SERPER_DOMAIN_FILTER=example.com,another.com
SERPER_LOCATION_HINT=California, United States
SERPER_OFFLINE_MODE=false
MCP_SANDBOX_REQUIRE_APPROVAL=true  # force clients to set `approved: true`

JSON-RPC 2.0 Protocol

All tool calls use JSON-RPC 2.0 format.

Request Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "tool_name",
    "arguments": {
      "arg1": "value1",
      "arg2": "value2"
    }
  }
}

Response Format

{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "content": "Tool output",
    "is_error": false
  }
}

Error Response

{
  "jsonrpc": "2.0",
  "id": 1,
  "error": {
    "code": -32603,
    "message": "Internal error",
    "data": "Tool execution failed"
  }
}

MCP Endpoint (POST /v1/mcp)

All JSON-RPC requests (initialize, tools/list, tools/call, prompts/list, etc.) go through a single streaming endpoint. When calling through Kong, use http://localhost:8000/v1/mcp; direct calls go to http://localhost:8091/v1/mcp.

curl -N http://localhost:8000/v1/mcp \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{
 "jsonrpc": "2.0",
 "id": 1,
 "method": "tools/list"
 }'

Because the service uses mcp-go's streaming HTTP server, responses are sent as Server-Sent Events (SSE). For simple calls you can omit -N, but streaming keeps the connection open for multi-part results (tool deltas, long-running sandbox jobs, etc.).

Response:

{
  "tools": [
    {
      "name": "google_search",
      "description": "Search Google for query results",
      "inputSchema": {
        "type": "object",
        "properties": {
          "q": { "type": "string", "description": "Search query" },
          "num": {
            "type": "integer",
            "description": "Number of results",
            "default": 10
          }
        },
        "required": ["q"]
      }
    },
    {
      "name": "scrape",
      "description": "Extract content from a URL",
      "inputSchema": {
        "type": "object",
        "properties": {
          "url": { "type": "string", "description": "URL to scrape" }
        },
        "required": ["url"]
      }
    },
    {
      "name": "python_exec",
      "description": "Execute code in a sandboxed environment",
      "inputSchema": {
        "type": "object",
        "properties": {
          "code": { "type": "string", "description": "Code to execute" },
          "language": {
            "type": "string",
            "enum": ["python", "javascript"],
            "default": "python"
          }
        },
        "required": ["code"]
      }
    }
  ]
}

Health Check

GET /healthz

# Via gateway
curl http://localhost:8000/mcp/healthz

# Direct
curl http://localhost:8091/healthz

Integration with Response API

The Response API uses MCP Tools for multi-step orchestration:

# Response API automatically calls MCP tools
curl -X POST http://localhost:8000/responses/v1/responses \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{
 "model": "jan-v2-30b",
 "input": "Search for Python async programming and summarize top 3 results",
 "stream": true
 }'

# Response API orchestrates:
# 1. Call google_search
# 2. Optionally call scrape/file_search_query
# 3. Stream deltas as the LLM produces the final response

Tool Chaining (via Response API)

The Response API enables tool chaining:

google_search
 v
scrape (on each result)
 v
python_exec (if needed for analysis)
 v
LLM API (final generation)

Max Depth: 8 tool calls Timeout per Tool: 45 seconds

Error Codes

Code Message Meaning
-32700 Parse error Invalid JSON
-32600 Invalid Request Missing method/params
-32601 Method not found Unknown tool
-32602 Invalid params Invalid parameters
-32603 Internal error Tool execution failed
-32000 Timeout Tool execution timeout

Related Services

  • Response API (Port 8082) - Tool orchestration
  • LLM API (Port 8080) - Final generation
  • Kong Gateway (Port 8000) - API routing
  • SandboxFusion - Code execution sandbox
  • Serper / SearXNG - Web search providers
  • Provider Configuration: services/mcp-tools/mcp-providers.md

See Also

Example: List Available Tools

curl -s http://localhost:8000/v1/mcp \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{
 "jsonrpc": "2.0",
 "id": 42,
 "method": "tools/list"
 }' | jq

Example: google_search

curl -s http://localhost:8000/v1/mcp \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{
 "jsonrpc": "2.0",
 "id": 2,
 "method": "tools/call",
 "params": {
 "name": "google_search",
 "arguments": {"q": "latest AI news", "num": 5}
 }
 }'

Example: scrape

curl -s http://localhost:8000/v1/mcp \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{
 "jsonrpc": "2.0",
 "id": 3,
 "method": "tools/call",
 "params": {
 "name": "scrape",
 "arguments": {"url": "https://docs.python.org/3/", "includeMarkdown": true}
 }
 }'

Example: Vector Store

# Index a note
curl -s http://localhost:8000/v1/mcp \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{
 "jsonrpc": "2.0",
 "id": 4,
 "method": "tools/call",
 "params": {
 "name": "file_search_index",
 "arguments": {
   "document_id": "notes-1",
   "text": "Menlo Platform docs live in jan-server/docs/*",
   "tags": ["docs","menlo"]
 }
 }
 }'

# Query it later
curl -s http://localhost:8000/v1/mcp \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{
 "jsonrpc": "2.0",
 "id": 5,
 "method": "tools/call",
 "params": {
 "name": "file_search_query",
 }
 }'

Example: Sandbox (python_exec)

curl -s http://localhost:8000/v1/mcp \
 -H "Authorization: Bearer <token>" \
 -H "Content-Type: application/json" \
 -d '{
 "jsonrpc": "2.0",
 "id": 6,
 "method": "tools/call",
 "params": {
 "name": "python_exec",
 "arguments": {"code": "import math; print(math.pi)"}
 }
 }'