mcpstore Documentation

MCPStore is primarily used to manage Model Context Protocol (MCP) services. Common management tasks include:

• Adding a new MCP service.
• Viewing currently active services and their configurations.
• Checking the health status of services.
• Inspecting the specific Tools, Prompts, and Resources provided by a service.
• Lifecycle management: Updating, restarting, or deleting services.

MCPStore is a unified management tool for Model Context Protocol (MCP) services.

Key distinction: MCPStore manages the MCP services themselves—including their availability and capabilities—rather than managing the Agents that use them.

Core Capabilities:

• Configuration Management: Save and modify MCP service configurations.
• Lifecycle Management: Start, stop, restart, and delete services.
• Health Monitoring: View service status and perform health checks.
• Service Discovery: Discover the Tool, Prompt, and Resource capabilities provided by services.
• Client Integration: Provide access for local programs, coding assistants, or other MCP clients.
• Deployment Flexibility: Manage local instances or connect to remote instances.

MCPStore is a management system for Model Context Protocol (MCP) services. Depending on your requirements, you can use it in the following ways:

• Manage MCP Services: Add, configure, monitor status, perform health checks, update, and delete MCP services.
• Local Usage: Manage MCP services running on your local machine using a Command Line Interface (CLI), Terminal User Interface (TUI), or a desktop application.
• Code Integration: Integrate MCPStore capabilities directly into your own Rust or Python projects.
• Remote Usage: Connect to and use an MCPStore instance running on a remote server.

MCPStore acts as a central hub (an instance) that manages multiple MCP services. The architecture follows this flow:

1. Users interact with an Entry Point (CLI, TUI, Desktop App, Web, Rust, or Python).
2. The Entry Point connects to an MCPStore Instance.
3. The MCPStore Instance manages and provides access to multiple MCP Services.
4. MCP Clients (such as programming assistants or other MCP-compatible tools) connect to the MCPStore Instance to consume services.

MCPStore provides multiple interfaces to interact with the same core system. These are different entry points to the same product, not separate products. While the underlying concepts are shared, the specific methods of interaction vary by interface:

• CLI (Command Line Interface)
• TUI (Terminal User Interface)
• Desktop App
• Web Interface
• Rust SDK/Integration
• Python SDK/Integration

Before using MCPStore, you should understand three fundamental concepts:

1. What MCPStore is: The core definition and purpose of the system.
2. How MCP services are managed: The lifecycle and mechanisms for controlling MCP services.
3. The relationship between Local, Remote, and Clients: How local instances, remote instances, and MCP clients (like programming assistants) interact within the ecosystem.

Depending on your use case, you can deploy MCPStore in two modes:

• Local Instance: Runs on your local machine. This is ideal for personal use and local development workflows.
• Remote Instance: Runs on a server. Local entry points or other devices connect to it, making it suitable for centralized management of MCP services across multiple environments.

All routes in this demo return a unified JSON envelope to ensure consistent client handling:

{
  "ok": true,
  "data": <payload>,
  "error": null,
  "message": "ok"
}

When a request fails, ok will be false, and the error field will contain the reason for failure, accompanied by an appropriate HTTP status code.

In a distributed setup, you can run a store instance in only_db=True mode. This instance does not manage or maintain the services itself; instead, it acts as a client that interacts with the shared database. All operations on MCP services in this mode will notify the primary environment (the one managing the actual processes) via events.

from mcpstore import MCPStore
from mcpstore.config import RedisConfig

redis_config = RedisConfig(
  host="127.0.0.1",
  port=6379,
  password=None,
  namespace="demo_namespace"
)

# Configure as a client-only instance
store = MCPStore.setup_store(cache=redis_config, only_db=True)

# Operations here will interact with the shared Redis state
store.for_store().list_services()

To prevent context overflow and isolate tools, you can group MCP services by agent_id. Using store.for_agent(agent_id) creates a logical subset of the global store. This subset mirrors most of the for_store() interface but only operates on services assigned to that specific agent.

agent_id1 = "agent1"
# This service is only visible to agent1
store.for_agent(agent_id1).add_service({"name": "mcpstore_wiki", "url": "https://example.com/mcp"})

agent_id2 = "agent2"
# This service is only visible to agent2
store.for_agent(agent_id2).add_service({"name": "gitodo", "command": "uvx", "args": ["gitodo"]})

# Retrieve tools for a specific agent
agent1_tools = store.for_agent(agent_id1).list_tools()