mcpgateway-sdk

Python SDK for MCP Gateway — the enterprise platform for hosting, managing, and securing MCP (Model Context Protocol) servers.

Installation

pip install mcpgateway-sdk

Quick start

import asyncio
from mcpgateway_sdk import MCPGateway

async def main():
    async with MCPGateway(api_key="sk-...", url="http://localhost:8000") as gw:
        # Semantic search for tools across all servers
        tools = await gw.tools.search("get current weather")
        print(tools[0].tool_name, tools[0].score)

        # Execute a tool
        result = await gw.tools.execute(
            "get_weather", {"city": "NYC"}, server_name="weather"
        )
        print(result)

asyncio.run(main())

Features

Servers — full CRUD, typed remote registration, readiness, lifecycle, health checks, bulk actions, catalog import, tool sync (with bundle-update control), tool overrides, credentials, OAuth config
Tools — semantic search, execute by name, lookup by server/tool name
Skills — create, upload, catalog import, package download
Script tools — upload a server-owned script-tool package (servers.create_script_tool_package)
Sessions — per-session tool scoping for multi-tenant isolation
Sandboxes — isolated execution environments with file I/O and code exec
Auth — API key management
Cache — server-side cache control

All resources are accessed as attributes on the client: gw.servers, gw.tools, gw.skills, gw.sessions, gw.sandboxes, gw.auth, gw.cache, gw.oauth_apps, and gw.oauth_templates.

Configuration

The client reads configuration from explicit parameters or environment variables:

Parameter	Environment variable	Default
`api_key`	`MCPGATEWAY_TOKEN`	—
`url`	`MCPGATEWAY_URL`	`http://localhost:8000`
`timeout`	—	`30.0`

import os
os.environ["MCPGATEWAY_TOKEN"] = "sk-..."
os.environ["MCPGATEWAY_URL"] = "https://gateway.example.com"

async with MCPGateway() as gw:  # picks up from env
    ...

Usage examples

All examples below assume gw is an active client from async with MCPGateway(...) as gw.

Manage servers

# List all running servers
servers = await gw.servers.list(status="running")

# Import a server from the built-in catalog
server = await gw.servers.import_from_catalog(
    registry="npm",
    registry_id="@anthropic/time-mcp",
    name="time-server",
)

# Start, stop, health check
await gw.servers.start(server.id)
health = await gw.servers.health(server.id)
await gw.servers.stop(server.id)

# Re-sync tools from the source. By default, new/renamed tools are also
# propagated into any bundles that curate this server. Check how many bundles
# would be affected, then opt out of the bundle update if you prefer.
usage = await gw.servers.bundle_usage(server.id)  # {"bundle_count": 3}
await gw.servers.sync_tools(server.id)                       # update bundles (default)
await gw.servers.sync_tools(server.id, update_bundles=False) # leave bundles alone

# Uploading a script-tool package works the same way (default on):
await gw.servers.create_script_tool_package(server.id, "package.zip")
await gw.servers.create_script_tool_package(server.id, "package.zip", update_bundles=False)

Register an authenticated remote MCP server

from mcpgateway_sdk.models import RemoteAuthentication, RemoteServerRegistration, ServerReadiness

# Probe first: only OAuth and no-auth can be safely preselected by the gateway.
probe = await gw.oauth_apps.probe_auth("https://mcp.example.com/mcp")
print(probe.outcome)

server = await gw.servers.register_remote(
    RemoteServerRegistration(
        name="example-remote",
        display_name="Example Remote",
        url="https://mcp.example.com/mcp",
        authentication=RemoteAuthentication(
            type="api_key",
            config={"location": "header", "name": "X-API-Key"},
            secrets={"api_key": "set-once-and-never-read-back"},
        ),
    )
)
if server.readiness is ServerReadiness.AWAITING_CREDENTIALS:
    print("A member still needs to connect their account")
elif server.readiness is ServerReadiness.FAILED:
    print(server.last_error)

The typed remote path supports only none, api_key, bearer, basic, and oauth2. It rejects HMAC and query-parameter API keys locally. servers.create(**fields) remains available for existing generic server workflows.

For OAuth, list a template and create the app before registering the server; the app response's id is the config["app_id"] value for RemoteAuthentication(type="oauth2", ...):

import os

from mcpgateway_sdk.models import OAuthAppCreate

template = (await gw.oauth_templates.list())[0]
app = await gw.oauth_apps.create(
    OAuthAppCreate(
        alias="example-oauth",
        name="Example OAuth",
        template_id=template.id,
        client_id="provider-issued-client-id",
        client_secret=os.environ["OAUTH_CLIENT_SECRET"],
    )
)
print(app.id)  # Pass this UUID as the remote OAuth2 config.app_id.

Search and execute tools

# Semantic search across all servers
results = await gw.tools.search("convert PDF to text", limit=3)
for r in results:
    print(f"{r.server_name}/{r.tool_name} — score: {r.score:.2f}")

# Execute a specific tool
output = await gw.tools.execute(
    "read_pdf",
    {"url": "https://example.com/report.pdf"},
    server_name="document-reader",
)

Work with skills

# Upload a skill from a local file
skill = await gw.skills.upload(file_path="./my_skill.md")

# Browse the skill catalog
entries = await gw.skills.catalog("builtin")

Sessions with scoped tools

# Allow specific tools + wildcard for entire servers
session = await gw.sessions.create(
    allowed_tool_names=["VVMCP__kb_finance", "HOTSPOT__*", "GMAIL__*"],
    denied_tool_names=["HOTSPOT__internal_debug"],
)

# Use the session ID for MCP connections with restricted tool access
print(session.id)

# Update only the deny list (allowed list unchanged)
session = await gw.sessions.update(
    session.id,
    denied_tool_names=["HOTSPOT__internal_debug", "HOTSPOT__admin_reset"],
)

# Refresh session activity
await gw.sessions.touch(session.id)

Sandbox execution

# Create a sandbox
sandbox = await gw.sandboxes.create(image="python:3.12")

# Execute code
result = await gw.sandboxes.exec(sandbox.id, command="python -c 'print(1+1)'")
print(result.stdout)

# Upload / download files
await gw.sandboxes.upload_file(sandbox.id, "data.csv", content=b"a,b\n1,2")
files = await gw.sandboxes.list_files(sandbox.id)

# Clean up
await gw.sandboxes.destroy(sandbox.id)

API key management

# Create a new API key
key = await gw.auth.create_api_key(name="ci-pipeline", expires_in_days=90)
print(key.key)  # Only shown once

# List and rotate keys
keys = await gw.auth.list_api_keys()
rotated = await gw.auth.rotate_api_key(keys[0].id)

SDK cache

# Store a value with TTL (default 300 seconds)
await gw.cache.set("last_run", {"status": "ok"}, ttl=600)

# Retrieve — returns None if key doesn't exist
value = await gw.cache.get("last_run")

Error handling

The SDK raises typed exceptions that map to HTTP status codes:

from mcpgateway_sdk import (
    GatewayError,    # Base — all API errors
    AuthError,       # 401 Unauthorized
    ForbiddenError,  # 403 Forbidden
    NotFoundError,   # 404 Not Found
    ConflictError,   # 409 Conflict
    ValidationError, # 422 Unprocessable Entity
    RateLimitError,  # 429 Too Many Requests
)

try:
    await gw.servers.get("nonexistent-id")
except NotFoundError:
    print("Server not found")
except GatewayError as e:
    print(f"API error [{e.status_code}]: {e.message}")

Version compatibility

The client automatically checks its version against the server on connect (via async with). If there is a major/minor mismatch, it emits a warning:

UserWarning: SDK version 0.16.0 does not match server version 0.17.0.
Update with: pip install --upgrade mcpgateway-sdk

Disable this check with MCPGateway(check_version=False).

MCP connection

Use the client to get connection details for direct MCP protocol access:

async with MCPGateway(api_key="sk-...") as gw:
    print(gw.mcp_url)       # http://localhost:8000/mcp/gateway
    print(gw.auth_headers)   # {"Authorization": "Bearer sk-..."}

Requirements

Python 3.11+
httpx >= 0.27
Pydantic >= 2.0

License

MIT

Metadata

Release files for mcpgateway-sdk 0.59.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mcpgateway-sdk 0.59.1
File	Size	Uploaded	Provenance
mcpgateway_sdk-0.59.1.tar.gz	139.6 kB	Sep 22, 2026	Without provenance	Details

Built distribution (wheel)

Table of built distributions (wheels) for mcpgateway-sdk 0.59.1
File	Interpreter	ABI	Platform	Reset
mcpgateway_sdk-0.59.1-py3-none-any.whl 68.0 kB Sep 22, 2026 Without provenance	Python 3	none	any	Details

Total release size: 207.5 kB

Release files / mcpgateway_sdk-0.59.1.tar.gz

Download URL	mcpgateway_sdk-0.59.1.tar.gz
Size	139.6 kB
Tags	Source
SHA-256 checksum How to use checksums	`0b3b0fd500aa8f2f18981be74ce1e80db099819ab1258789ae67afa452aa07a4`
BLAKE2b-256 checksum How to use checksums	`73b6af95768aba745e9cd301c952c7f25ad196d91ef2e6ccd32305db6ea7600f`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Release files / mcpgateway_sdk-0.59.1-py3-none-any.whl

Download URL	mcpgateway_sdk-0.59.1-py3-none-any.whl
Size	68.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`1ebd7f53c62431d5a33fbc9aaad9f16bd1c8821480fe2407b262e2155b5b364b`
BLAKE2b-256 checksum How to use checksums	`04b6065a0251b270fa27a7263f494353b1fee17ccccaa74faaf54edb5826a63f`
Upload date	Sep 22, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/7.0.0 CPython/3.12.3`

Security for mcpgateway-sdk 0.59.1

Report project as malware

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.