Skip to main content
Glama
sagemcp

Sage MCP

by sagemcp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Remote

License Python Docker Build Status Discord

About The Project

Sage MCP is a production-ready platform that enables you to run multiple isolated MCP servers with built-in OAuth/API key authentication for 23+ services. It provides a web interface and CLI for managing tenants and connectors, making it easy to integrate Claude Desktop with various external services.

Key Features:

  • Multi-tenant architecture with path-based isolation

  • Full MCP protocol support (Streamable HTTP, WebSocket, SSE) with protocol version negotiation

  • Server pooling with LRU eviction (5,000 max instances, 30-min TTL)

  • Session management via Mcp-Session-Id with resumable SSE streams

  • Token-bucket rate limiting (configurable RPM per tenant)

  • External MCP server hosting via stdio subprocess (GenericMCPConnector)

  • OAuth 2.0 integration with tenant-level and user-level tokens

  • Field-level encryption at rest (Fernet/AES) and API key authentication

  • Prometheus metrics, structured JSON logging, and Kubernetes health probes

  • Progressive rollout via feature flags (SAGEMCP_ENABLE_*)

Related MCP server: Outsource MCP

Screenshots

Supported Connectors

340 tools across 23 native connectors, plus unlimited external MCP server support.

Architecture

High-Level System Architecture

graph TB
    subgraph Client["Client Layer"]
        CD[Claude Desktop]
        WEB[Web Browser]
    end

    subgraph Platform["SageMCP Platform"]
        subgraph Frontend["Frontend :3001"]
            UI[React UI]
        end

        subgraph Backend["Backend :8000"]
            subgraph Middleware["Middleware"]
                RL["Rate Limiter
                Token Bucket"]
                CORS_MW["CORS / Origin
                Validation"]
                CT["Content-Type
                Validation"]
            end

            API[FastAPI Admin API]

            subgraph MCPCore["MCP Core"]
                POOL["ServerPool
                LRU · 5000 max"]
                SESS["SessionManager
                Mcp-Session-Id"]
                TRANSPORT["Transport
                HTTP POST · WS · SSE"]
                EBUF["EventBuffer
                Resumable Streams"]
            end

            subgraph Connectors["Connectors"]
                NATIVE["Native Plugins
                GitHub · GitLab · Bitbucket
                Jira · Linear · Confluence
                Slack · Discord · Teams
                Gmail · Outlook
                Google Docs · Sheets · Slides
                Notion · Zoom
                Excel · PowerPoint"]
                EXT_MCP["External MCP Servers
                via ProcessManager + stdio"]
            end

            subgraph Observability["Observability"]
                PROM["Prometheus /metrics"]
                LOGS["Structured JSON Logs"]
                HEALTH["Health Probes
                /health/live · ready · startup"]
            end
        end

        subgraph Database["Database"]
            DB[("PostgreSQL /
            Supabase")]
        end
    end

    subgraph External["External Services"]
        EXT["GitHub · GitLab · Bitbucket
        Jira · Linear · Confluence
        Slack · Discord · Teams
        Gmail · Outlook · Google
        Notion · Zoom · Microsoft APIs"]
    end

    CD -->|"HTTP POST / WebSocket"| TRANSPORT
    WEB -->|HTTPS| UI
    UI -->|REST API| API
    TRANSPORT --> POOL
    POOL --> SESS
    SESS --> Connectors
    NATIVE -->|OAuth| EXT
    EXT_MCP -->|stdio| EXT
    API -->|ORM| DB

    style CD fill:#e1f5ff
    style WEB fill:#e1f5ff
    style UI fill:#fff3e0
    style API fill:#f3e5f5
    style POOL fill:#e8f5e9
    style SESS fill:#e8f5e9
    style TRANSPORT fill:#e8f5e9
    style EBUF fill:#e8f5e9
    style NATIVE fill:#e8f5e9
    style EXT_MCP fill:#e8f5e9
    style DB fill:#fce4ec
    style EXT fill:#e0f2f1
    style RL fill:#fff9c4
    style CORS_MW fill:#fff9c4
    style CT fill:#fff9c4
    style PROM fill:#f3e5f5

View Full Architecture Documentation | Includes 10+ detailed diagrams covering OAuth flows, multi-tenancy, database schema, deployment, and more.

Built With

FastAPI React SQLAlchemy MCP Prometheus Docker

Security

  • Encryption at rest -- All OAuth tokens, API keys, and connector credentials encrypted via Fernet (AES-128-CBC + HMAC), key derived from SECRET_KEY via PBKDF2-SHA256 (480K iterations).

  • API key authentication -- Three scope tiers (platform_admin, tenant_admin, tenant_user) with bcrypt-hashed storage and SHA-256 LRU cache. Feature-flagged via SAGEMCP_ENABLE_AUTH.

  • Transport security -- CORS origin validation, Content-Type enforcement, per-tenant token-bucket rate limiting.

Getting Started

Prerequisites

  • Docker and Docker Compose

  • Python 3.11+ (for local development)

  • PostgreSQL or Supabase account

Installation

  1. Clone the repository

    git clone https://github.com/mvmcode/SageMCP.git
cd SageMCP

  2. Setup environment

    cp .env.example .env
# Edit .env with your OAuth credentials (optional for testing)

  3. Start the platform

    make setup
make up

  4. Access the application

Usage

Management Options

SageMCP provides two ways to manage your platform:

  1. Web Interface - Visual interface at http://localhost:3001

  2. Command-Line Interface (CLI) - Powerful CLI for automation and DevOps

Quick Start (Web Interface)

  1. Open the web interface at http://localhost:3001

  2. Create a new tenant

  3. Add a connector (e.g., GitHub) and configure OAuth

  4. Copy the MCP server URL for Claude Desktop

Quick Start (CLI)

# Install CLI
pip install -e ".[cli]"

# Initialize configuration
sagemcp init

# Create a tenant
sagemcp tenant create --slug my-tenant --name "My Tenant"

# Add a connector
sagemcp connector create my-tenant --type github --name "GitHub"

# Configure OAuth (opens browser)
sagemcp oauth authorize my-tenant github

# Test MCP tools
sagemcp mcp tools my-tenant <connector-id>

# Interactive REPL
sagemcp mcp interactive my-tenant <connector-id>

Full CLI Documentation | CLI Design Document

Claude Desktop Configuration

Add to your Claude Desktop config:

{
  "mcpServers": {
    "sage-mcp": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-everything"],
      "env": {
        "MCP_SERVER_URL": "ws://localhost:8000/api/v1/{tenant-slug}/mcp"
      }
    }
  }
}

User-Level OAuth Tokens

SageMCP supports per-user OAuth tokens in addition to tenant-level credentials. See User-Level OAuth Tokens for HTTP and WebSocket examples.

Feature Flags & Configuration

SageMCP uses feature flags for progressive rollout of v2 capabilities. All flags default to false and can be enabled via environment variables.

Flag

Description

Default

SAGEMCP_ENABLE_SERVER_POOL

LRU server-instance pool (5,000 max, 30-min TTL)

false

SAGEMCP_ENABLE_SESSION_MANAGEMENT

Mcp-Session-Id tracking and SSE replay

false

SAGEMCP_ENABLE_METRICS

Prometheus /metrics endpoint

false

SAGEMCP_ENABLE_AUTH

API key authentication and authorization

false

Additional configuration settings:

Setting

Description

Default

SECRET_KEY

Key for Fernet encryption and token signing (min 16 chars)

required

RATE_LIMIT_RPM

Requests per minute per tenant (token bucket)

100

CORS_ALLOWED_ORIGINS

Comma-separated allowed CORS origins

* (dev)

MCP_ALLOWED_ORIGINS

Comma-separated allowed MCP Origin headers

--

SAGEMCP_BOOTSTRAP_ADMIN_KEY

One-time bootstrap key to create first platform admin

--

Development

Running Tests

# Backend tests
make test-backend

# Frontend tests
make test-frontend

# All tests with coverage
make test-coverage

Available Commands

make help            # Show all available commands
make build           # Build Docker images
make up              # Start all services
make down            # Stop all services
make logs            # View logs
make shell           # Open shell in app container
make clean           # Clean up containers and volumes

Adding New Connectors

  1. Create a new connector class in src/sage_mcp/connectors/

  2. Implement the BaseConnector interface

  3. Register with @register_connector decorator

  4. Add to the connector enum

See existing connectors in src/sage_mcp/connectors/ for examples.

Deployment

Docker Compose (Development)

make up

Kubernetes (Production)

Deploy with PostgreSQL:

helm install sage-mcp ./helm

Deploy with Supabase:

helm install sage-mcp ./helm \
  --set database.provider=supabase \
  --set postgresql.enabled=false \
  --set supabase.url=https://your-project.supabase.co \
  --set supabase.serviceRoleKey=your-service-role-key

Roadmap

  • Tool policy language (per-connector tool enable/disable rules)

  • OpenTelemetry tracing

  • Redis-backed session persistence

See the open issues for a full list of proposed features and known issues.

Contributing

Contributions are what make the open source community amazing! Any contributions you make are greatly appreciated.

  1. Fork the Project

  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)

  3. Commit your Changes (git commit -m 'Add some AmazingFeature')

  4. Push to the Branch (git push origin feature/AmazingFeature)

  5. Open a Pull Request

License

Distributed under the Apache 2.0 License. See LICENSE for more information.

Contact

Acknowledgments

Available Tools

13 tools
echoEcho ToolB

Echoes back the input string

ParametersJSON Schema
NameRequiredDescriptionDefault
messageYesMessage to echo

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided; description only says 'echoes back the input string'. Lacks details on side effects, error handling, or return format. For a simple tool, minimal disclosure.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence, front-loaded with essential information. No wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple echo tool with one required parameter, description is mostly complete. Implies return of same string, though explicit mention would be ideal. No output schema, but 'echoes back' suffices.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%; parameter 'message' already described as 'Message to echo'. Description adds no additional semantic value, baseline 3.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description uses specific verb 'echoes' and resource 'input string', clearly stating the tool's function. Distinct from sibling tools like 'get-annotated-message'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. Sibling tools have different purposes but no explicit when/when-not advice.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-annotated-messageGet Annotated Message ToolC

Demonstrates how annotations can be used to provide metadata about content.

ParametersJSON Schema
NameRequiredDescriptionDefault
messageTypeYesType of message to demonstrate different annotation patterns
includeImageNoWhether to include an example image

TDQS

C2.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as side effects, permissions, or output structure. It only says it 'demonstrates annotations' without elaboration.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is concise but insufficient. It lacks necessary information such as output format or usage context.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema and low complexity, the description should clarify what the tool returns (e.g., an annotated message). It fails to do so, leaving the agent guessing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the input schema already documents both parameters (messageType with enum, includeImage with default). The description adds no additional meaning beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Demonstrates how annotations can be used to provide metadata about content' is vague and meta. It does not clearly state what the tool does (e.g., retrieves a message with annotations) or distinguish it from other tools.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus its siblings. The context signals list 13 other tools with no differentiation criteria.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-envPrint Environment ToolA

Returns all environment variables, helpful for debugging MCP server configuration

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A4.3/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries the burden. It states the tool returns environment variables, but does not disclose behavioral traits like output format, security implications (e.g., sensitive data exposure), or that it's a read-only operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence with no wasted words. Every part is essential and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with zero parameters, no output schema, and no nested objects, the description is complete. It states purpose and usage context, sufficient for an AI agent to select and invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist, and schema coverage is 100%. The description adds the 'debugging' context, which provides additional meaning beyond the schema. Baseline 4 is appropriate given no parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'returns all environment variables' with a specific verb and resource. The additional context 'helpful for debugging MCP server configuration' distinguishes it from sibling tools, none of which retrieve environment variables.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states usage context 'debugging MCP server configuration', which guides when to use. No explicit when-not or alternative tools are needed as the tool's function is unique among siblings.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-resource-referenceGet Resource Reference ToolC

Returns a resource reference that can be used by MCP clients

ParametersJSON Schema
NameRequiredDescriptionDefault
resourceTypeNoText
resourceIdNoID of the text resource to fetch

TDQS

C2.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must fully disclose behavior. It only states the return type (resource reference) without mentioning side effects, authorization, or response format.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single efficient sentence. However, brevity comes at the cost of completeness; it could be expanded without losing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple tool with 2 parameters and no output schema, the description fails to explain what a 'resource reference' is or how the response should be used. It lacks sufficient context for an AI agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 50% (only resourceId has a description). The tool description adds no additional meaning to either parameter, leaving the resourceType enum undocumented.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose3/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description 'Returns a resource reference that can be used by MCP clients' states the basic action but does not differentiate from sibling tools like get-resource-links or get-structured-content. It is not a tautology but lacks specificity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description does not mention any prerequisites, constraints, or use case.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-structured-contentGet Structured Content ToolB

Returns structured content along with an output schema for client data validation

ParametersJSON Schema
NameRequiredDescriptionDefault
locationYesChoose city

Output Schema

ParametersJSON Schema
NameRequiredDescription
temperatureYesTemperature in celsius
conditionsYesWeather conditions description
humidityYesHumidity percentage

TDQS

B3.1/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description must fully inform about behavior. It does not disclose side effects, authentication needs, rate limits, or error handling. It implies a read operation but lacks explicit safety guarantees.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that is direct and front-loaded with the action. It contains no fluff and is appropriately sized for the simple tool.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

The tool has an output schema, so return values are covered externally. However, the description does not explain the relationship between the location parameter and the returned structured content, leaving some context missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema covers 100% of parameters with a clear description for 'location'. The tool description adds no additional parameter context beyond what the schema provides, meeting the baseline but not exceeding it.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool returns structured content with an output schema for client data validation. It uses a specific verb 'returns' and specifies the resource. However, it does not explicitly differentiate from sibling tools, leaving some ambiguity about uniqueness.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. Sibling tools like 'echo' exist, but no comparison or usage context is given, leaving agents without decision support.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-sumGet Sum ToolB

Returns the sum of two numbers

ParametersJSON Schema
NameRequiredDescriptionDefault
aYesFirst number
bYesSecond number

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description should disclose behavioral traits, but it does not mention error handling, overflow behavior, or limitations. It only states the basic operation.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, efficient sentence with no redundant information, making it highly concise and front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simplicity of the tool (two numbers, no output schema), the description adequately explains the behavior. However, it could be improved by mentioning the return type or potential edge cases.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% coverage with descriptions for both parameters. The tool description adds no extra meaning beyond what the schema provides, meeting the baseline expectation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Returns' and the resource 'sum of two numbers', making the purpose unambiguous. The sibling tools are unrelated, so no confusion arises.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. There is no mention of context, prerequisites, or when not to use it.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get-tiny-imageGet Tiny Image ToolA

Returns a tiny MCP logo image.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.6/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It does not disclose whether the tool is read-only, has side effects, or any other behavioral traits beyond returning an image.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that efficiently conveys the purpose without any wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (no params, no output schema), the description is largely complete. It could mention the expected output format or size, but it is adequate for basic understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Tool has zero parameters and schema coverage is 100%, so the description does not need to add parameter information. Baseline of 4 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states that the tool returns a tiny MCP logo image, which is a specific verb+resource. It differentiates from siblings as none of them are image-related.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives. The description does not indicate any prerequisites or context for invoking this tool.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

gzip-file-as-resourceGZip File as Resource ToolA

Compresses a single file using gzip compression. Depending upon the selected output type, returns either the compressed data as a gzipped resource or a resource link, allowing it to be downloaded in a subsequent request during the current session.

ParametersJSON Schema
NameRequiredDescriptionDefault
nameNoName of the output fileREADME.md.gz
dataNoURL or data URI of the file content to compresshttps://raw.githubusercontent.com/modelcontextprotocol/servers/refs/heads/main/README.md
outputTypeNoHow the resulting gzipped file should be returned. 'resourceLink' returns a link to a resource that can be read later, 'resource' returns a full resource object.resourceLink

TDQS

A3.6/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description should disclose behavioral traits. It mentions output modes and that the result can be used later, but does not detail side effects, authorization needs, or file size limits. It's adequate but not comprehensive.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is two sentences, front-loading the core purpose. Every word adds value, with no fluff or repetition. It is concise and well-structured.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple compression tool with 3 fully described parameters and no output schema, the description covers the essential behavior. It could mention that the original file is not modified, but overall it is sufficiently complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100% from the input schema, so the description adds minimal extra meaning beyond restating the output type options. The baseline score of 3 is appropriate as the schema already provides good parameter descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the action ('compresses a single file using gzip compression') and the resource, with specific details about output types. It effectively distinguishes from sibling tools like echo or get-env by focusing on a compression operation.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives, nor any exclusions or prerequisites. It simply describes what it does without context for decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

simulate-research-querySimulate Research QueryA

Simulates a deep research operation that gathers, analyzes, and synthesizes information. Demonstrates MCP task-based operations with progress through multiple stages. If 'ambiguous' is true and client supports elicitation, sends an elicitation request for clarification.

ParametersJSON Schema
NameRequiredDescriptionDefault
topicYesThe research topic to investigate
ambiguousNoSimulate an ambiguous query that requires clarification (triggers input_required status)

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It discloses progress stages and elicitation behavior for ambiguous queries, but does not cover all behavioral aspects like side effects or final output nature.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, front-loaded with core purpose, no redundant information. Every sentence adds value.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no output schema, description should explain return value; it mentions progress stages but not final output. Adequate for a simulation tool but missing return specification.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, baseline 3. Description adds extra meaning to 'ambiguous' parameter by specifying it triggers input_required status and elicitation request, surpassing schema documentation.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states it simulates a deep research operation and demonstrates MCP task-based operations, distinguishing it from sibling tools like echo or get-sum which are unrelated.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies use for demonstration/simulation but does not explicitly state when to use or not use this tool compared to alternatives, leaving usage context inferential.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

toggle-simulated-loggingToggle Simulated LoggingB

Toggles simulated, random-leveled logging on or off.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries full burden. It only states it toggles logging on/off, without detailing what 'simulated' means, side effects, or state persistence.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

One short sentence, no wasted words. Could be slightly expanded without losing conciseness, but currently efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Adequate for a simple toggle tool with no parameters, but lacks context on scope (global/session) and effect on other tools. Siblings provide similar patterns, so more detail would help.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist; schema coverage is 100%. The description adds no parameter info but none is needed. Baseline score of 4 for zero-parameter tools.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses specific verb 'toggles' and resource 'simulated, random-leveled logging', clearly distinguishing it from sibling tools like 'toggle-subscriber-updates'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool vs alternatives. With sibling tools like 'toggle-subscriber-updates', the description should clarify scenarios for each.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

toggle-subscriber-updatesToggle Subscriber UpdatesA

Toggles simulated resource subscription updates on or off.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

TDQS

A3.8/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description discloses the basic action (toggling on/off) but, in the absence of annotations, does not clarify side effects, persistence, or state changes beyond the immediate toggle.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single, concise sentence that directly states the tool's purpose with no unnecessary words or repetition.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple no-parameter toggle tool, the description is mostly complete, though a brief note on the scope or effect of 'subscriber updates' would enhance understanding.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

With no parameters and 100% schema coverage, the description adds no parameter details but is adequate given the simplicity; baseline of 4 applies per zero-param rule.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly specifies the verb 'toggles' and the resource 'simulated resource subscription updates', making it distinct from sibling tools like 'toggle-simulated-logging'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when to use this tool versus alternatives, such as 'toggle-simulated-logging' or other sibling tools. The agent lacks context for decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

trigger-long-running-operationTrigger Long Running Operation ToolC

Demonstrates a long running operation with progress updates.

ParametersJSON Schema
NameRequiredDescriptionDefault
durationNoDuration of the operation in seconds
stepsNoNumber of steps in the operation

TDQS

C2.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It only mentions 'progress updates' but omits critical details such as whether the operation is destructive, how to cancel it, or any side effects. This is insufficient for an agent to understand the tool's impact.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness3/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single short sentence, which is concise but at the expense of clarity. It is front-loaded with the weak verb 'Demonstrates', reducing effectiveness. While not verbose, it lacks structure and important details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (two simple numeric parameters) and absence of an output schema, the description should provide sufficient behavioral context. It fails to do so, omitting safety, cancellation, and result details. The mention of progress updates is the only meaningful addition.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has 100% description coverage for both parameters ('duration' and 'steps'), so the schema already documents their meaning. The description adds no extra semantic value beyond noting progress updates, which is not parameter-specific. Baseline score of 3 applies.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose2/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description says 'Demonstrates a long running operation', which essentially restates the tool's name without specifying a concrete action. 'Demonstrates' is vague and does not clearly indicate that the tool triggers an operation, making it a tautology.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is provided on when or why to use this tool. The description does not mention use cases, prerequisites, or alternatives among sibling tools, leaving the agent without context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 13 tool updatesv0.1.0
    • First observedecho
    • First observedget-annotated-message
    • First observedget-env
    • First observedget-resource-links
    • First observedget-resource-reference
    • First observedget-structured-content
    • First observedget-sum
    • First observedget-tiny-image
    • First observedgzip-file-as-resource
    • First observedsimulate-research-query
    • First observedtoggle-simulated-logging
    • First observedtoggle-subscriber-updates
    • First observedtrigger-long-running-operation
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.4/5.0

Scored across 13 tools

Disambiguation5/5

Each tool has a clearly distinct purpose: echo returns input, get-env returns environment variables, get-sum adds numbers, etc. No two tools serve overlapping functions.

Naming Consistency5/5

All tool names follow a consistent lowercase-hyphenated verb-noun pattern (e.g., get-annotated-message, gzip-file-as-resource, toggle-subscriber-updates). No mixing of styles.

Tool Count5/5

With 13 tools, the count is well-scoped for a demonstration server that showcases various MCP features. It's neither too sparse nor overly heavy.

Completeness4/5

The tool set covers a broad range of MCP capabilities (resources, annotations, logging, long-running ops, etc.), but as a demo it misses some common features like database or file system operations.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Remote MCP Server with Bearer

    huanshenyi
    F
    license
    Not graded
    quality
    D
    maintenance
    A Cloudflare Workers-based MCP server implementation that supports OAuth login and bearer token authentication, allowing secure connection from MCP clients like Claude Desktop and the MCP Inspector.
    1
    -

  • Outsource MCP

    gwbischof
    A
    license
    A
    quality
    D
    maintenance
    An MCP server that enables AI applications to access 20+ model providers (including OpenAI, Anthropic, Google) through a unified interface for text and image generation.
    2
    30
    MIT

  • MCP OAuth Sample

    raxITlabs
    F
    license
    Not graded
    quality
    D
    maintenance
    A production-ready MCP OAuth 2.1 server implementation with analytics and security monitoring, enabling secure authentication for MCP clients like Claude Desktop and Cursor.
    4
    -