AgentRuntime MCP SDK (Python)
Opinionated SDK for MCP connectors using FastMCP with the same Control integration as agentruntime-mcp-go: optional POST /mcp/config, env merge, and request metadata (run token, instance id).
There is no mandatory legacy standalone token/HMAC middleware chain in front of every request. Probe-style auth is the Bearer run token (or X-MCP-Token) and headers AgentRuntime sends; optional auth.mode in config.yaml is reserved for future templates and does not switch Control gating off.
Install
pip install agentruntime-mcp
Runtimes
| Entry | When to use | HTTP |
|---|---|---|
run(config_path) |
Decorator-only tool() modules; tools registered from config.yaml / build_schemas |
/mcp |
run_with_registry(config_path, *names) |
Plugins registered with register_adapter; one process, one MCP server |
/mcp |
run_with_router(config_path) |
Same registry, monolith routing (Go RunWithRouter / TS runWithRouter parity) |
/{adapter}/mcp plus optional webhook routes on the same ASGI app |
Use register_adapter for anything that should share a process with other adapters. Keep plain run() for single-connector demos that only use decorators and YAML tools.
Webhooks: Implement register_webhook(self, mux: ServeMux) on the adapter. Paths are registered on the root Starlette app before adapter mounts (same dispatch order as Go/TS). Operators expose vendor callbacks as https://<host>:<port><path> (same host/port as MCP).
Minimal example
from pydantic import BaseModel, Field
from agentruntime.mcp.decorators import tool
from agentruntime.mcp.runtime import run
from fastmcp import Context
class In(BaseModel):
a: float = Field(...)
b: float = Field(...)
class Out(BaseModel):
result: float
expression: str
@tool(name="add", input_model=In, output_model=Out)
def add(a: float, b: float, ctx: Context) -> Out:
region = ctx.config.region # resolved config when schema + Control are used
return Out(result=a + b, expression=f"{a} + {b}")
if __name__ == "__main__":
run("config.yaml")
Config (config.yaml)
server:name,host,port,stateless_httptracing: enable OpenTelemetry when dependencies are presentconfig: declarative schema for Control /GET /mcp/config/schema
Env overrides: HOST, PORT (see docs/mcp/mcp_env.md).
Example:
server:
name: "MyConnector"
host: "127.0.0.1"
port: 8012
stateless_http: true
tracing:
enabled: false
config:
apiKey:
type: string
displayName: API Key
required: true
Control config resolution
When the adapter registers at least one config key:
- Set
MCP_CONTROL_SERVER_URLto your control-service base URL. - The SDK may call
POST /mcp/configwith the run token from the request and your schema. - Set
MCP_CONFIG_FETCH_REQUIRED=falsefor local work without Control (when you still declare schema keys).
See docs/mcp/mcp_env.md for the full variable list.
Proxy (library)
from agentruntime.mcp.proxy import run_proxy
run_proxy(
target_url="http://127.0.0.1:8000/mcp",
overlay_file="tools.yaml",
host="127.0.0.1",
port=8010,
)
Tool organization (toolorg)
Large connectors can build publish metadata for Control catalog grouping. Parity with Go toolorg — see MCP_SDK_PARITY.md.
from agentruntime.mcp.toolorg import publisher_metadata, Metadata
meta = publisher_metadata("clickup_get_task", Metadata())
# → display_name, suggested_group, suggested_tags for mcp_tools.metadata
Per-request caller bearer (for downstream HTTP): request_bearer_from_context().
TypeScript sibling SDK
For Node deployments, use the monorepo package packages/agentruntime-mcp-ts (@agentruntime-labs/agentruntime-mcp): official @modelcontextprotocol/server, Zod 4, runWithRouter.
Examples in this repo
connectors/py-connectors/resend-connector— Python Resend connector (illustrative layout)
Releasing
See ../RELEASE.md (Python section): lightweight Git tags (v0.1.0, v0.1.1), bump version in pyproject.toml, do not commit __pycache__ / *.egg-info/.
Metadata
Release files for agentruntime-mcp 0.3.3
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| agentruntime_mcp-0.3.3.tar.gz | 29.7 kB | Without provenance | Details for agentruntime_mcp-0.3.3.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| agentruntime_mcp-0.3.3-py3-none-any.whl | Python 3 | none | any | Details for agentruntime_mcp-0.3.3-py3-none-any.whl |
Total release size: 61.4 kB
Release files / agentruntime_mcp-0.3.3.tar.gz
| Download URL | agentruntime_mcp-0.3.3.tar.gz |
|---|---|
| Size | 29.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b02292f452078b87e73bb30b62e9be3a86bc3acd651600b84f330fc7a3e41480
|
|
BLAKE2b-256 checksum How to use checksums |
3b744cb23af1d9e8992e472364d771b2b75e87877e2128668675a71784c1c69d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.1
|
Release files / agentruntime_mcp-0.3.3-py3-none-any.whl
| Download URL | agentruntime_mcp-0.3.3-py3-none-any.whl |
|---|---|
| Size | 31.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cb405caef9a433f24ee0c0a7a52cbe0c7c209ccaf7e1d51b739dede6af6e6354
|
|
BLAKE2b-256 checksum How to use checksums |
d4ab7d0277591ca281b27b70940f03cadcb162cd8de8af9f246ea063ca137ace
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.1
|
Security for agentruntime-mcp 0.3.3
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.