## MCPLoader
MCPLoader is a small helper module that lets you define and consume multiple MCP servers (stdio, SSE, or Streamable HTTP) from a JSON configuration. It uses `pydantic-ai` MCP clients and validates configuration with Pydantic models.
## Features
- **HTTP (SSE / Streamable HTTP)** and **STDIO** server types
- Configuration validation with **Pydantic**
- Multiple MCP servers from a single JSON file
- Simple Python API: pass a config path, get ready-to-use server clients
## Installation
Use it as a module inside your own codebase. Required dependencies:
```bash
pip install mcploader
```
or
```bash
uv add mcploader
```
## Quick start
```python
from mcploader import MCPServerManager
# Provide your configuration file path (e.g., config/http.json or data/mcp/http.json)
manager = MCPServerManager("config/http.json")
servers = manager.servers # serialized list of MCPServer
from pydantic_ai import Agent
agent = Agent('openai:gpt-4o', toolsets=servers)
async def main():
async with agent:
await agent.run('Ask something here...')
import asyncio
if __name__ == '__main__':
asyncio.run(main())
```
## Configuration
Configuration is a JSON object with a root key `mcpServers`. Each key under `mcpServers` is a server name; the value is its configuration.
### General schema
```json
{
"mcpServers": {
"<serverName>": { ... }
}
}
```
Each server can be one of two forms:
- **STDIO**: `StdioServerParameters`
- **HTTP**: `ServerParameters` (contains a `transport` body)
### HTTP (SSE / Streamable HTTP) example
```json
{
"mcpServers": {
"server1": {
"transport": {
"type": "streamable-http", // or "sse"
"url": "http://127.0.0.1:8000/mcp",
"headers": {
"Authorization": "Bearer your-token-here",
"Content-Type": "application/json",
"User-Agent": "Claude-Desktop/1.0",
"X-API-Version": "v1"
},
"timeout": 30000,
"readTimeout": 300000,
"maxRetries": 5
}
}
}
}
```
`type` is normalized to lowercase and must be one of:
- `sse`
- `streamable-http`
### STDIO example
```json
{
"mcpServers": {
"server1": {
"command": "deno",
"args": ["run", "-N", "-R=node_modules", "-W=node_modules", "--node-modules-dir=auto", "jsr:@pydantic/mcp-run-python", "stdio"],
"env": { "OPENAI_API_KEY": "..." },
"cwd": "/usr/path/to",
"timeout": 10,
"readTimeout": 300,
"maxRetries": 3
}
}
}
```
### Fields and types (summary)
- **HTTP (ServerParameters.transport: ServerBody)**
- **type**: `"sse" | "streamable-http"`
- **url**: a valid URL
- **headers**: `dict[str, str]` (optional)
- **timeout**: request timeout in ms (default 30000)
- **readTimeout**: read timeout in ms (default 300000)
- **maxRetries**: retry count (default 5)
- **STDIO (StdioServerParameters)**
- **command**: command to execute (e.g., `deno`, `python`)
- **args**: command arguments (list)
- **env**: environment variables (key/value)
- **cwd**: working directory (optional)
- **timeout**: timeout in seconds (default 30)
- **readTimeout**: read timeout in seconds (default 300)
- **maxRetries**: retry count (default 1)
> Note: `ServerParameters.server_type` defaults to `"http"`, `StdioServerParameters.server_type` defaults to `"io"`. These are used internally to select the proper client.
## Folder layout
This repository includes sample configurations under `data/`.
- `data/http.json`: Streamable HTTP example
- `data/sse.json`: SSE example
- `data/stdio.json`: STDIO example
- **Passing paths**: Provide the absolute/relative path directly to `MCPServerManager`, e.g., `MCPServerManager("data/mcp/http.json")`.
- **Schema**: JSON files under `data/` use the same schema; the root must have `mcpServers`, each key defining a server.
- **Environment variants**: You can create `data/mcp/prod/http.json`, `data/mcp/dev/http.json`, etc., and select the appropriate file at runtime.
## API surface
- **`MCPServerManager(config_path: str)`**: Reads the JSON config and validates it with `ServerConfig`.
- **`MCPServerManager.servers -> list[MCPServer]`**: On first access, creates MCP clients (`MCPServerSSE`, `MCPServerStreamableHTTP`, `MCPServerStdio`) according to the config and caches them.
Feel free to reach me from [contact@tomris.dev](mailto:contact@tomris.dev) or my [GitHub](https://github.com/fswair) address.
Raw data
{
"_id": null,
"home_page": "https://github.com/fswair/mcploader",
"name": "mcploader",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mcp, mcp config management, pydantic-ai, mcp server, mcp client, mcp config, mcp servers",
"author": "Mert Sirakaya",
"author_email": "contact@tomris.dev",
"download_url": "https://files.pythonhosted.org/packages/1f/31/699cbbd1dc8133a56dfd8b66486a460147e45bda430b8b931d8e68dd4907/mcploader-0.1.0.tar.gz",
"platform": null,
"description": "## MCPLoader\n\nMCPLoader is a small helper module that lets you define and consume multiple MCP servers (stdio, SSE, or Streamable HTTP) from a JSON configuration. It uses `pydantic-ai` MCP clients and validates configuration with Pydantic models.\n\n## Features\n- **HTTP (SSE / Streamable HTTP)** and **STDIO** server types\n- Configuration validation with **Pydantic**\n- Multiple MCP servers from a single JSON file\n- Simple Python API: pass a config path, get ready-to-use server clients\n\n## Installation\nUse it as a module inside your own codebase. Required dependencies:\n\n```bash\npip install mcploader\n```\n\nor\n\n```bash\nuv add mcploader\n```\n\n## Quick start\n```python\nfrom mcploader import MCPServerManager\n\n# Provide your configuration file path (e.g., config/http.json or data/mcp/http.json)\nmanager = MCPServerManager(\"config/http.json\")\n\nservers = manager.servers # serialized list of MCPServer\n\nfrom pydantic_ai import Agent\n\nagent = Agent('openai:gpt-4o', toolsets=servers)\n\nasync def main():\n async with agent:\n await agent.run('Ask something here...')\n\nimport asyncio\n\nif __name__ == '__main__':\n asyncio.run(main())\n```\n\n## Configuration\nConfiguration is a JSON object with a root key `mcpServers`. Each key under `mcpServers` is a server name; the value is its configuration.\n\n### General schema\n```json\n{\n \"mcpServers\": {\n \"<serverName>\": { ... }\n }\n}\n```\n\nEach server can be one of two forms:\n- **STDIO**: `StdioServerParameters`\n- **HTTP**: `ServerParameters` (contains a `transport` body)\n\n### HTTP (SSE / Streamable HTTP) example\n```json\n{\n \"mcpServers\": {\n \"server1\": {\n \"transport\": {\n \"type\": \"streamable-http\", // or \"sse\"\n \"url\": \"http://127.0.0.1:8000/mcp\",\n \"headers\": {\n \"Authorization\": \"Bearer your-token-here\",\n \"Content-Type\": \"application/json\",\n \"User-Agent\": \"Claude-Desktop/1.0\",\n \"X-API-Version\": \"v1\"\n },\n \"timeout\": 30000,\n \"readTimeout\": 300000,\n \"maxRetries\": 5\n }\n }\n }\n}\n```\n\n`type` is normalized to lowercase and must be one of:\n- `sse`\n- `streamable-http`\n\n### STDIO example\n```json\n{\n \"mcpServers\": {\n \"server1\": {\n \"command\": \"deno\",\n \"args\": [\"run\", \"-N\", \"-R=node_modules\", \"-W=node_modules\", \"--node-modules-dir=auto\", \"jsr:@pydantic/mcp-run-python\", \"stdio\"],\n \"env\": { \"OPENAI_API_KEY\": \"...\" },\n \"cwd\": \"/usr/path/to\",\n \"timeout\": 10,\n \"readTimeout\": 300,\n \"maxRetries\": 3\n }\n }\n}\n```\n\n### Fields and types (summary)\n- **HTTP (ServerParameters.transport: ServerBody)**\n - **type**: `\"sse\" | \"streamable-http\"`\n - **url**: a valid URL\n - **headers**: `dict[str, str]` (optional)\n - **timeout**: request timeout in ms (default 30000)\n - **readTimeout**: read timeout in ms (default 300000)\n - **maxRetries**: retry count (default 5)\n- **STDIO (StdioServerParameters)**\n - **command**: command to execute (e.g., `deno`, `python`)\n - **args**: command arguments (list)\n - **env**: environment variables (key/value)\n - **cwd**: working directory (optional)\n - **timeout**: timeout in seconds (default 30)\n - **readTimeout**: read timeout in seconds (default 300)\n - **maxRetries**: retry count (default 1)\n\n> Note: `ServerParameters.server_type` defaults to `\"http\"`, `StdioServerParameters.server_type` defaults to `\"io\"`. These are used internally to select the proper client.\n\n## Folder layout\nThis repository includes sample configurations under `data/`.\n\n- `data/http.json`: Streamable HTTP example\n- `data/sse.json`: SSE example\n- `data/stdio.json`: STDIO example\n\n- **Passing paths**: Provide the absolute/relative path directly to `MCPServerManager`, e.g., `MCPServerManager(\"data/mcp/http.json\")`.\n- **Schema**: JSON files under `data/` use the same schema; the root must have `mcpServers`, each key defining a server.\n- **Environment variants**: You can create `data/mcp/prod/http.json`, `data/mcp/dev/http.json`, etc., and select the appropriate file at runtime.\n\n## API surface\n- **`MCPServerManager(config_path: str)`**: Reads the JSON config and validates it with `ServerConfig`.\n- **`MCPServerManager.servers -> list[MCPServer]`**: On first access, creates MCP clients (`MCPServerSSE`, `MCPServerStreamableHTTP`, `MCPServerStdio`) according to the config and caches them.\n\nFeel free to reach me from [contact@tomris.dev](mailto:contact@tomris.dev) or my [GitHub](https://github.com/fswair) address.\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "This package is a small helper module that lets you define and consume multiple MCP servers (stdio, SSE, or Streamable HTTP) from a JSON configuration. It uses `pydantic-ai` MCP clients and validates configuration with Pydantic models.",
"version": "0.1.0",
"project_urls": {
"Bug Reports": "https://github.com/fswair/mcploader/issues",
"Homepage": "https://github.com/fswair/mcploader",
"Source": "https://github.com/fswair/mcploader"
},
"split_keywords": [
"mcp",
" mcp config management",
" pydantic-ai",
" mcp server",
" mcp client",
" mcp config",
" mcp servers"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "d0a3927c9d3a7b252c7882599af5720c1d9935faa05d90fbe558fa79f86b7db7",
"md5": "ca2afdfadcc4bf26364e7ba5cb01a0c8",
"sha256": "bfc93d47aafa164c13a36a82beaa069715db2641968dca699b6c54861d620ea7"
},
"downloads": -1,
"filename": "mcploader-0.1.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ca2afdfadcc4bf26364e7ba5cb01a0c8",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 5238,
"upload_time": "2025-08-21T15:26:57",
"upload_time_iso_8601": "2025-08-21T15:26:57.224474Z",
"url": "https://files.pythonhosted.org/packages/d0/a3/927c9d3a7b252c7882599af5720c1d9935faa05d90fbe558fa79f86b7db7/mcploader-0.1.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1f31699cbbd1dc8133a56dfd8b66486a460147e45bda430b8b931d8e68dd4907",
"md5": "6b3c16bab658cf8a2e1c0604ff07411c",
"sha256": "5697427786c281092e49d6bce6a7a77295e62c52f427ae8ebdf46683ae01fe86"
},
"downloads": -1,
"filename": "mcploader-0.1.0.tar.gz",
"has_sig": false,
"md5_digest": "6b3c16bab658cf8a2e1c0604ff07411c",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 4739,
"upload_time": "2025-08-21T15:26:58",
"upload_time_iso_8601": "2025-08-21T15:26:58.370566Z",
"url": "https://files.pythonhosted.org/packages/1f/31/699cbbd1dc8133a56dfd8b66486a460147e45bda430b8b931d8e68dd4907/mcploader-0.1.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-21 15:26:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "fswair",
"github_project": "mcploader",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"requirements": [
{
"name": "pydantic",
"specs": []
},
{
"name": "pydantic-ai",
"specs": []
}
],
"lcname": "mcploader"
}
JSON
