core

module
v0.0.2 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Dec 19, 2025 License: Apache-2.0

README

License Test GoDoc GoReportCard codecov

MCP Any Logo

MCP Any: Configuration-Driven MCP Server

One server, Infinite possibilities.

MCP Any revolutionizes how you interact with the Model Context Protocol (MCP). It is not just another MCP proxy or aggregator—it is a powerful Universal Adapter that turns any API into an MCP-compliant server through simple configuration.

Traditional MCP adoption requires running a separate server binary for every tool or service you want to expose. This leads to "binary fatigue," complex local setups, and maintenance nightmares.

MCP Any solves this with a Single Binary approach:

  1. Install once: Run a single mcpany server instance.
  2. Configure everything: Load lightweight YAML/JSON configurations to capability-enable different APIs (REST, gRPC, GraphQL, Command-line).
  3. Run anywhere: No need for npx, python, or language-specific runtimes for each tool.

❓ Philosophy: Configuration over Code

We believe you shouldn't have to write and maintain new code just to expose an existing API to your AI assistant.

  • Metamcp / Onemcp vs. MCP Any: While other tools might proxy existing MCP servers (aggregator pattern), MCP Any creates them from scratch using your existing upstream APIs.
  • No More "Sidecar hell": Instead of running 10 different containers for 10 different tools, run 1 mcpany container loaded with 10 config files.
  • Ops Friendly: Centralize authentication, rate limiting, and observability in one robust layer.
Comparison with Traditional MCP Servers

Unlike traditional "Wrapper" MCP servers (like mcp-server-postgres, mcp-server-github, etc.) which are compiled binaries dedicated to a single service, MCP Any is a generic runtime.

Feature Traditional MCP Server (e.g., mcp-server-postgres) MCP Any
Architecture Code-Driven Wrapper: Wraps internal API calls with MCP annotations. Config-Driven Adapter: Maps existing API endpoints to MCP tools via config.
Deployment 1 Binary per Service: Need 10 different binaries for 10 services. 1 Binary for All: One mcpany binary handles N services.
Updates Recompile & Redistribute: Internal API change = New Binary release. Update Config: API change = Edit YAML/JSON file & reload.
Maintenance High: Manage dependencies/versions for N projects. Low: Upgrade one core server; just swap config files.
Extensibility Write code (TypeScript/Python/Go). Write JSON/YAML.

Most "popular" MCP servers today are bespoke binaries. If the upstream API changes, you must wait for the maintainer to update the code, release a new version, and then you must redeploy. With MCP Any, you simply update your configuration file to match the new API signature—zero downtime, zero recompilation.

✨ Key Features

  • Dynamic Tool Registration & Auto-Discovery: Automatically discover and register tools from various backend services. For gRPC and OpenAPI, simply provide the server URL or spec URL—MCP Any handles the rest (no manual tool definition required).
  • Multiple Service Types: Supports a wide range of service types, including:
    • gRPC: Register services from .proto files or by using gRPC reflection.
    • OpenAPI: Ingest OpenAPI (Swagger) specifications to expose RESTful APIs as tools.
    • HTTP: Expose any HTTP endpoint as a tool.
    • GraphQL: Expose a GraphQL API as a set of tools, with the ability to customize the selection set for each query.
  • Advanced Service & Safety Policies:
    • Safety: Control which tools are exposed to the AI to limit context (reduce hallucinations) and prevent dangerous actions (e.g., blocking DELETE operations).
    • Performance: Configure Caching and Rate Limiting to optimize performance and protect upstream services.
  • MCP Any Proxy: Proxy and re-expose tools from another MCP Any instance.
  • Upstream Authentication: Securely connect to your backend services using:
    • API Keys
    • Bearer Tokens
    • Basic Auth
    • mTLS
  • Unified API: Interact with all registered tools through a single, consistent API based on the Model Context Protocol.
  • Multi-User & Multi-Profile: Securely support multiple users with distinct profiles, each with its own set of enabled services and granular authentication.
  • Advanced Configuration: Customize tool behavior with Merge Strategies and Profile Filtering.
  • Extensible: Designed to be easily extended with new service types and capabilities.

⚡ Quick Start (5 Minutes)

Ready to give your AI access to real-time data? Let's connect a public Weather API to Gemini CLI (or any MCP client) using MCP Any.

1. Prerequisites
  • Go: Ensure you have Go installed (1.23+ recommended).
  • Gemini CLI: If not installed, see the installation guide.

(Prefer building from source? See Getting Started for build instructions.)

2. Configuration

We will use the pre-built wttr.in configuration available in the examples directory: examples/popular_services/wttr.in/config.yaml.

Quick Start: Weather Service

  1. Run the Server:

    Choose one of the following methods to run the server.

    Option 1: Remote Configuration (Recommended)

    Fastest way to get started. No need to clone the repository.

    docker run -d --rm --name mcpany-server \
  -p 50050:50050 \
  ghcr.io/mcpany/server:dev-latest \
  run --config-path https://raw.githubusercontent.com/mcpany/core/main/examples/popular_services/wttr.in/config.yaml

    Option 2: Local Configuration

    Best if you want to modify the configuration or use your own. Requires cloning the repository.

    # Clone the repository
git clone https://github.com/mcpany/core.git
cd core

# Run with local config mounted
docker run -d --rm --name mcpany-server \
  -p 50050:50050 \
  -v $(pwd)/examples/popular_services/wttr.in/config.yaml:/config.yaml \
  ghcr.io/mcpany/server:dev-latest \
  run --config-path /config.yaml

    Tip: Need detailed logs? Add the --debug flag to the end of the run command.

  2. Connect Gemini CLI:

    gemini mcp add --transport http --trust mcpany http://localhost:50050

  3. Chat!

    Ask your AI about the weather:

    gemini -m gemini-2.5-flash -p "What is the weather in London?"

    The AI will:

    1. Call the tool (e.g., wttrin_<hash>.get_weather).
    2. mcpany will proxy the request to https://wttr.in.
    3. The AI receives the JSON response and answers your question!

Ask about the moon phase:

gemini -m gemini-2.5-flash -p "What is the moon phase?"

The AI will:

  1. Call the get_moon_phase tool.
  2. mcpany will proxy the request to https://wttr.in/moon.
  3. The AI receives the ASCII art response and describes it!

For more complex examples, including gRPC, OpenAPI, and authentication, check out docs/reference/configuration.md.

💡 More Usage

Once the server is running, you can interact with it using its JSON-RPC API.

🛠️ Development Guide

Prerequisites
  • Go: Version 1.23+
  • Docker: For running tests and building images.
  • Protoc: For generating protobuf files (handled by make prepare).
Setup

Run the following command to set up the development environment, including installing tools and dependencies:

make prepare
Building

To build the server binary locally:

make build

The binary will be located at build/bin/server.

Testing

To run the test suite:

make test

This includes unit tests, integration tests, and end-to-end (E2E) tests.

Linting

To run linters:

make lint

We use golangci-lint and pre-commit hooks.

Code Standards
  • Documentation: All public functions, methods, and types must be documented. Use go run tools/check_doc.go <directory> to verify documentation coverage.
  • Linting: Ensure make lint passes before submitting code.
  • Testing: Ensure make test passes.
Running Locally

After building, you can run the server locally:

./build/bin/server run --config-path examples/popular_services/wttr.in/config.yaml

🤝 Contributing

Contributions are welcome! Please feel free to open an issue or submit a pull request.

🗺️ Roadmap

Check out our Roadmap to see what we're working on and what's coming next.

📄 License

This project is licensed under the terms of the LICENSE file.

Directories

Path Synopsis
cmd
mock_mcp_server command
Package main implements a mock MCP server for testing.
 Package main implements a mock MCP server for testing.
server command
webhooks command
Package main implements a simple webhook server for testing.
 Package main implements a simple webhook server for testing.
webhooks/hooks
Package hooks defines the system webhook handlers.
 Package hooks defines the system webhook handlers.
worker command
Package main implements the worker service.
 Package main implements the worker service.
examples
demo/remote-config command
Package main implements a mock server for remote configuration.
 Package main implements a mock server for remote configuration.
demo/stdio/my-tool command
Package main implements a demo tool.
 Package main implements a demo tool.
upstream_service_demo/file-upload command
Package main implements a file upload demo server.
 Package main implements a file upload demo server.
upstream_service_demo/graphql/server command
Package main implements a GraphQL upstream service demo.
 Package main implements a GraphQL upstream service demo.
upstream_service_demo/http/client command
Package main implements a demo HTTP client for the upstream service.
 Package main implements a demo HTTP client for the upstream service.
upstream_service_demo/http/server command
Package main is a demo time server.
 Package main is a demo time server.
upstream_service_demo/http/server/weather_server command
Package main implements the weather server for the upstream service demo.
 Package main implements the weather server for the upstream service demo.
upstream_service_demo/openapi/client command
Package main implements an OpenAPI client demo.
 Package main implements an OpenAPI client demo.
upstream_service_demo/openapi/server command
Package main implements an OpenAPI upstream service demo.
 Package main implements an OpenAPI upstream service demo.
upstream_service_demo/webrtc/client command
Package main implements a demo WebRTC client.
 Package main implements a demo WebRTC client.
upstream_service_demo/webrtc/server command
Package main implements a WebRTC server demo.
 Package main implements a WebRTC server demo.
upstream_service_demo/websocket command
Package main implements a demo WebSocket client.
 Package main implements a demo WebSocket client.
upstream_service_demo/websocket/client command
Package main implements a demo WebSocket client.
 Package main implements a demo WebSocket client.
upstream_service_demo/websocket/echo_server/server command
Package main implements a simple WebSocket echo server for demonstration purposes.
 Package main implements a simple WebSocket echo server for demonstration purposes.
upstream/grpc/greeter_server module
pkg
admin
app
Package app provides the main application logic.
 Package app provides the main application logic.
appconsts
Package appconsts contains application-level constants for the MCP Any server, such as the application name and version.
 Package appconsts contains application-level constants for the MCP Any server, such as the application name and version.
auth
Package auth provides authentication and authorization functionality.
 Package auth provides authentication and authorization functionality.
bus
Package bus defines the message bus interface and implementations.
 Package bus defines the message bus interface and implementations.
bus/memory
Package memory provides in-memory implementations of the bus interface.
 Package memory provides in-memory implementations of the bus interface.
bus/nats
Package nats provides a NATS-based message bus implementation.
 Package nats provides a NATS-based message bus implementation.
bus/redis
Package redis provides a Redis implementation of the bus.
 Package redis provides a Redis implementation of the bus.
cli
Package cli provides a JSON executor for CLI commands.
 Package cli provides a JSON executor for CLI commands.
client
Package client provides the MCP client implementation.
 Package client provides the MCP client implementation.
command
Package command provides interfaces and implementations for executing commands.
 Package command provides interfaces and implementations for executing commands.
config
Package config provides configuration management for the application.
 Package config provides configuration management for the application.
consts
Package consts defines common constants used across the application.
 Package consts defines common constants used across the application.
health
Package health provides health check functionality.
 Package health provides health check functionality.
logging
Package logging provides logging utilities for the application.
 Package logging provides logging utilities for the application.
mcpserver
Package mcpserver implements the MCP server functionality.
 Package mcpserver implements the MCP server functionality.
metrics
Package metrics provides gRPC interceptors for metrics.
 Package metrics provides gRPC interceptors for metrics.
middleware
Package middleware provides HTTP middleware for the application.
 Package middleware provides HTTP middleware for the application.
pool
Package pool provides a generic connection pool implementation.
 Package pool provides a generic connection pool implementation.
prompt
Package prompt provides prompt management functionality.
 Package prompt provides prompt management functionality.
resilience
Package resilience provides resilience patterns such as circuit breakers and retries.
 Package resilience provides resilience patterns such as circuit breakers and retries.
resource
Package resource provides resource management functionality.
 Package resource provides resource management functionality.
service
Package service provides resilience patterns.
 Package service provides resilience patterns.
serviceregistry
Package serviceregistry provides service registry functionality.
 Package serviceregistry provides service registry functionality.
telemetry
Package telemetry provides functions for initializing and managing telemetry.
 Package telemetry provides functions for initializing and managing telemetry.
testutil
Package testutil provides test utilities and mocks.
 Package testutil provides test utilities and mocks.
tool
Package tool defines the interface for tools that can be executed by the upstream service.
 Package tool defines the interface for tools that can be executed by the upstream service.
transformer
Package transformer provides functionality for transforming and parsing data.
 Package transformer provides functionality for transforming and parsing data.
update
Package update provides functionality for self-updating the application.
 Package update provides functionality for self-updating the application.
upstream
Package upstream provides the upstream service implementation.
 Package upstream provides the upstream service implementation.
upstream/command
Package command provides command execution functionality.
 Package command provides command execution functionality.
upstream/factory
Package factory provides upstream factory functionality.
 Package factory provides upstream factory functionality.
upstream/graphql
Package graphql provides GraphQL upstream integration.
 Package graphql provides GraphQL upstream integration.
upstream/grpc
Package grpc provides gRPC upstream integration.
 Package grpc provides gRPC upstream integration.
upstream/grpc/protobufparser
Package protobufparser provides a parser for Protocol Buffers.
 Package protobufparser provides a parser for Protocol Buffers.
upstream/http
upstream/mcp
Package mcp provides MCP upstream integration.
 Package mcp provides MCP upstream integration.
upstream/openapi
Package openapi provides OpenAPI integration for the upstream service.
 Package openapi provides OpenAPI integration for the upstream service.
upstream/webrtc
Package webrtc provides WebRTC upstream integration.
 Package webrtc provides WebRTC upstream integration.
upstream/websocket
Package websocket provides WebSocket upstream integration.
 Package websocket provides WebSocket upstream integration.
util
Package util provides utility functions for Docker and other shared functionality.
 Package util provides utility functions for Docker and other shared functionality.
util/schemaconv
Package schemaconv provides utilities for converting between schema formats.
 Package schemaconv provides utilities for converting between schema formats.
util/testutil
Package testutil provides testing utilities.
 Package testutil provides testing utilities.
validation
Package validation provides validation utilities for config files and other inputs.
 Package validation provides validation utilities for config files and other inputs.
worker
Package worker provides background worker functionality.
 Package worker provides background worker functionality.
proto
admin/v1
api/v1
Package v1 is a reverse proxy.
 Package v1 is a reverse proxy.
bus
config/v1
examples/userservice/v1
examples/weather/v1
mcp_options/v1
mcp_router/v1
tests
framework
Package framework provides testing framework utilities.
 Package framework provides testing framework utilities.
integration
integration/cmd/command-tester command
Package main is a helper command for integration tests.
 Package main is a helper command for integration tests.
integration/cmd/mocks/grpc_authed_weather_server command
Package main implements a mock gRPC authenticated weather server for testing.
 Package main implements a mock gRPC authenticated weather server for testing.
integration/cmd/mocks/grpc_weather_server command
Package main implements a mock gRPC weather server.
 Package main implements a mock gRPC weather server.
integration/cmd/mocks/http_authed_echo_server command
Package main implements a mock HTTP authenticated echo server for testing.
 Package main implements a mock HTTP authenticated echo server for testing.
integration/cmd/mocks/http_caching_server command
Package main provides a mock HTTP caching server for integration testing.
 Package main provides a mock HTTP caching server for integration testing.
integration/cmd/mocks/http_echo_server command
Package main provides a mock HTTP echo server for integration testing.
 Package main provides a mock HTTP echo server for integration testing.
integration/cmd/mocks/openapi_weather_server command
Package main implements a mock OpenWeatherMap server.
 Package main implements a mock OpenWeatherMap server.
integration/cmd/mocks/prompt-server command
Package main implements a mock prompt server for integration tests.
 Package main implements a mock prompt server for integration tests.
integration/cmd/mocks/webrtc_weather_server command
Package main implements a mock WebRTC weather server for testing.
 Package main implements a mock WebRTC weather server for testing.
integration/cmd/mocks/websocket_echo_server command
Package main provides a mock WebSocket echo server for integration tests.
 Package main provides a mock WebSocket echo server for integration tests.
integration/upstream
license command
Package main is a script to remove license headers from files.
 Package main is a script to remove license headers from files.
license-header-remover command
Package main implements a tool to remove license headers.
 Package main implements a tool to remove license headers.
upstream_service
grpc/greeter_server module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.