MCP Capabilities

This page explains the capabilities exposed by the Sufy MCP server, including the supported JSON-RPC methods, available tools, request headers, and common request examples.

Endpoint And Transport

The MCP service is exposed through a single HTTP endpoint:

POST /mcp

Notes:

• Transport is HTTP JSON-RPC.
• GET /mcp is not supported for SSE on this server.
• DELETE /mcp is not supported.

Supported MCP Methods

The server currently handles these MCP methods:

• initialize
• ping
• tools/list
• tools/call
• notifications/initialized

Current capability scope:

• Tools: supported
• Resources: not implemented
• Prompts: not implemented

Request Headers

Each request must use Content-Type: application/json.

The server also understands these MCP-specific headers:

• mcp-method: optional, but if provided it must match the JSON-RPC method
• mcp-protocol-version: required for non-initialize requests
• mcp-name: optional for tools/call, but if provided it must match params.name

Compatibility note:

• some MCP clients, including Cursor, may omit mcp-method and mcp-name
• the server accepts requests without these headers and relies on the JSON-RPC body

Supported protocol versions:

• 2025-06-18
• 2025-03-26

Available Tools

The server currently exposes four tools.

search_sufy

Search across indexed Sufy documentation pages.

Arguments:

{
  "query": "bucket lifecycle",
  "limit": 5
}

Behavior:

• query is required
• limit is optional
• limit is clamped to the range 1 to 50

Use it when:

• you know the topic but not the exact page path
• you want ranked matches with snippets

list_docs_sufy

List all indexed documentation pages.

Arguments:

{}

Behavior:

• returns page title, description, route, and URL
• does not filter by keyword

Use it when:

• you want to inspect the full indexed page set
• you want to discover valid routes before calling get_doc_content_sufy

get_doc_content_sufy

Read a full documentation page by route.

Arguments:

{
  "path": "/storage-service/overview"
}

Behavior:

• path is required
• the path must match a documentation route, not a markdown file path

Use it when:

• you already know the exact route
• you need the complete page content

query_docs_filesystem_sufy

Run a read-only query against the virtual documentation filesystem.

Arguments:

{
  "command": "tree / -L 2"
}

Behavior:

• command is required
• the command runs against a virtual docs filesystem rooted at /
• this is read-only and supports a small command subset only

Use it when:

• you want to inspect docs by file path
• you want shell-like browsing without exposing a real filesystem
• you want to grep markdown content directly

Virtual Docs Filesystem Commands

query_docs_filesystem_sufy supports these commands:

• ls [path]
• tree [path] [-L depth]
• cat <file...>
• head [-n N | -N] <file...>
• rg [-C N] <pattern> [path]

Examples:

{ "command": "ls /" }

{ "command": "tree /storage-service -L 2" }

{ "command": "cat /storage-service/overview.md" }

{ "command": "head -n 20 /index.md" }

{ "command": "rg -C 2 \"upload token\" /storage-service" }

Path rules:

• root is /
• markdown files use virtual paths such as /index.md
• nested docs use virtual paths such as /storage-service/overview.md

Important note:

• rg uses JavaScript regular expression matching internally, so its behavior is similar to ripgrep for basic searches but not fully identical

Request Flow

Typical client flow:

1. Call initialize
2. Send notifications/initialized
3. Call tools/list
4. Call tools/call with one of the supported tool names

Request Examples

Initialize

curl -X POST https://developer.sufy.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'mcp-method: initialize' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-06-18"
    }
  }'

Send Initialized Notification

curl -X POST https://developer.sufy.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'mcp-method: notifications/initialized' \
  -H 'mcp-protocol-version: 2025-06-18' \
  -d '{
    "jsonrpc": "2.0",
    "method": "notifications/initialized"
  }'

List Tools

curl -X POST https://developer.sufy.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'mcp-method: tools/list' \
  -H 'mcp-protocol-version: 2025-06-18' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/list",
    "params": {}
  }'

Call search_sufy

curl -X POST https://developer.sufy.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'mcp-method: tools/call' \
  -H 'mcp-name: search_sufy' \
  -H 'mcp-protocol-version: 2025-06-18' \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "search_sufy",
      "arguments": {
        "query": "bucket lifecycle",
        "limit": 5
      }
    }
  }'

Call list_docs_sufy

curl -X POST https://developer.sufy.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'mcp-method: tools/call' \
  -H 'mcp-name: list_docs_sufy' \
  -H 'mcp-protocol-version: 2025-06-18' \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "list_docs_sufy",
      "arguments": {}
    }
  }'

Call get_doc_content_sufy

curl -X POST https://developer.sufy.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'mcp-method: tools/call' \
  -H 'mcp-name: get_doc_content_sufy' \
  -H 'mcp-protocol-version: 2025-06-18' \
  -d '{
    "jsonrpc": "2.0",
    "id": 5,
    "method": "tools/call",
    "params": {
      "name": "get_doc_content_sufy",
      "arguments": {
        "path": "/storage-service/overview"
      }
    }
  }'

Call query_docs_filesystem_sufy

curl -X POST https://developer.sufy.com/mcp \
  -H 'Content-Type: application/json' \
  -H 'mcp-method: tools/call' \
  -H 'mcp-name: query_docs_filesystem_sufy' \
  -H 'mcp-protocol-version: 2025-06-18' \
  -d '{
    "jsonrpc": "2.0",
    "id": 6,
    "method": "tools/call",
    "params": {
      "name": "query_docs_filesystem_sufy",
      "arguments": {
        "command": "tree / -L 2"
      }
    }
  }'

Error Cases To Expect

Common request errors:

• mcp-method header does not match the JSON-RPC method
• mcp-name does not match params.name
• unsupported mcp-protocol-version
• missing required tool arguments such as query, path, or command
• unknown MCP method
• unknown tool name

Capability Summary

In short, this MCP server currently provides:

• tool discovery through tools/list
• documentation search through search_sufy
• document index listing through list_docs_sufy
• full page retrieval through get_doc_content_sufy
• virtual filesystem inspection through query_docs_filesystem_sufy

It does not currently provide writable operations, MCP resources, or MCP prompts.