Skip to main content

prism-ai-mcp-server

MCP tool registration and dispatch over a consumer-supplied ServerTransport, with in-memory and authenticated loopback HTTP implementations. Python 3.10+, typed module prism_mcp_server. No stdio, sessions, push, resources or prompts.

Both protocols are served on the same transport and the same tool registry:

  • Stateless (2026-07-28): server/discover, then tools/list and tools/call, each carrying its version and client capabilities in params._meta.
  • Handshake (2025-11-25, 2025-06-18, 2025-03-26, 2024-11-05): initialize, notifications/initialized (answered 202), ping, tools/list and tools/call, for clients that always open with initialize, such as Codex. No session id is issued, so every request stands alone. An unknown requested revision is answered with 2025-11-25.

A request carrying any stateless _meta key is held to the stateless rules. Bearer and Origin checks, the gate and the result guard apply to both protocols in the same way. SUPPORTED_PROTOCOL_VERSIONS lists every version served, newest first, and protocol-versions.json publishes the same list.

Server(..., instructions="...") sets the server's instructions: guidance a client may give its model, sent in the initialize and server/discover results. Because it reaches the model, it comes only from your own configuration, fixed at construction; no request can set it. It must be a non-empty string of at most 16 KiB.

The sole runtime dependency is prism-ai-mcp; there are zero third-party runtime dependencies. Shared definitions/errors/guards come from prism_mcp. Python keeps the existing names ErrorCode and ToolResult. The local JsonObject = dict[str, Any] alias adds no runtime behavior. The official mcp SDK is in the dev extra only, reserved for phase 3 reference-client tests; production code does not import it.

from prism_mcp import ToolDefinition, ToolResult
from prism_mcp_server import InMemoryTransport, JsonObject, Server, ToolContext

transport = InMemoryTransport()
server = Server("example", transport)


def echo(args: JsonObject, context: ToolContext) -> ToolResult:
    return ToolResult(str(args.get("text", "")))


server.register(
    ToolDefinition(
        "echo",
        "Echo text",
        {
            "type": "object",
            "properties": {"text": {"type": "string"}},
        },
    ),
    echo,
)
# Inside your event loop: await server.listen(), await transport.request(...),
# then await server.close(). Synchronous and awaitable handlers are accepted.

Handlers take arguments plus {server, tool, headers} context and return the shared ToolResult. Registration snapshots definitions; duplicate names fail. Invalid mirrored annotations raise mirrored_parameter_refused, disappear from tools/list, and cannot run. Listed definitions preserve the client's digest.

ToolGate defaults to allow_all on the server, unlike the client's deny-by-default trust posture. Registration explicitly chooses what is served; an embedder's custom gate may refuse calls before handlers run. TrustPolicy does not apply inbound. Default outbound ResultGuard caps UTF-8 text at 64 KiB for both success and is_error results, without provenance framing; clients apply that framing once. Custom guards can intentionally transform text.

Server gates may return a boolean or an awaitable boolean. The asynchronous server awaits the verdict before permitting execution; async def returning False refuses the call. The sibling Python client's synchronous API is unchanged.

Only Mcp-Param-* headers reach handlers. The prefix is required and stripped case-insensitively; context keys are lowercase. Raw Authorization, Cookie, Origin and other unnamespaced headers stay private. Shared MirroredParameters resolve nested string/integer/boolean fields into arguments before the gate. Conflicting body/header values, ambiguous headers and invalid primitive encodings are refused. Integers use the shared JS-safe range for cross-language agreement. Other application argument validation belongs to handlers.

tools/list and tools/call require params['_meta'] with io.modelcontextprotocol/protocolVersion: '2026-07-28', io.modelcontextprotocol/clientCapabilities: {}. io.modelcontextprotocol/clientInfo: {name: 'example', version: '1'} is optional. Older revisions raise shared unsupported_protocol_version, naming both revisions. server/discover, tools/list and tools/call are supported. Discovery advertises supportedVersions: ['2026-07-28'] and capabilities: {tools: {}} regardless of the probe's requested version, including absent, older or unknown versions. The probe needs no params, _meta, capabilities or client identity, creates no session, and does not change server state. It uses the same HTTP bearer and Origin checks as tool requests. Every successful result includes resultType: 'complete' and _meta['io.modelcontextprotocol/serverInfo'] identifying the serving software as {name: 'prism-ai-mcp-server', version: '0.1.0'}. Discovery and tool lists include ttlMs: 0, cacheScope: 'private'; callers re-fetch to observe registration changes. Tool call results also carry {content: [{type: 'text', text: ...}], isError: ...}; failures raise shared McpError for transport mapping. Arbitrary handler diagnostic messages are excluded; a shared error category is retained.

In-memory listen() returns a memory:// identifier and token: None, not HTTP credentials or a dialable URL. Requests have no fixed timeout. close() releases pending request waiters, rejects further requests and is idempotent. Cancellation of handler-owned work is best-effort; an embedder must clean up application work that suppresses cancellation. SDK conformance and consumer acceptance remain phase 3.

For HTTP, replace the transport with LoopbackHttpTransport():

from prism_mcp_server import LoopbackHttpTransport, Server

transport = LoopbackHttpTransport()
server = Server("example", transport)
# Register application tools. Inside your event loop:
# endpoint = await server.listen()
# Give endpoint["url"] and endpoint["token"] privately to the client.
# Each POST needs Authorization: Bearer <token> and Content-Type: application/json.
# Send JSON-RPC 2.0 with id, method and the per-request params["_meta"] above.
# await server.close() when the embedder shuts down.

The HTTP URL is http://127.0.0.1:<port>/mcp. port defaults to 0 (an OS-chosen port); the bind address is fixed to literal 127.0.0.1. token is generated at startup with secrets.token_hex(32), or may be supplied as a keyword argument. Configured tokens must be non-empty bearer-token strings; whitespace is refused before listening. HTTP always returns a real token; only memory returns None. The URL alone does not authorize a client. Keep the token out of URLs and logs. Every request requires Authorization: Bearer <token>; comparison uses fixed-size SHA-256 digests and hmac.compare_digest.

Requests without Origin may proceed with valid credentials. A browser Origin must exactly match the listener's own origin by default. allowed_origins replaces that allow-list with explicit http://127.0.0.1:<port> / https://[::1]:<port> origins (either scheme is supported); arbitrary hostnames, paths, wildcard origins and non-loopback addresses are refused at startup. No browser CORS/preflight support is provided. GET, upgrades, CONNECT and SSE-only requests are refused; an Accept header offering both JSON and SSE receives JSON.

POSTs require Content-Length and JSON content; chunked uploads, batches, notifications and ambiguous duplicate headers are refused. max_request_bytes defaults to 1 MiB. Responses carry the same request id and either result or a JSON-RPC error with the shared Prism category in error.data.code; arbitrary diagnostic messages are withheld. HTTP refusal uses 401 for credentials and 403 for Origin. There is no fixed request or socket timeout. The stdlib HTTP listener uses daemon threads for HTTP I/O; registered handlers run on the calling asyncio loop. close() releases every socket, including incomplete headers and held long-polls, before resolving. Application cancellation remains best-effort.

Local setup: create a virtual environment and install -e .[dev] against the published sibling dependency. Gates: python -m pytest, python -m mypy --strict src tests, python -m ruff check ., python -m ruff format --check .. No remote, publishing workflow or tag is configured here. The complete suite includes a real 310-second HTTP long-poll and takes about six minutes. SDK reference-client conformance is not part of this phase.

Metadata

Release files for prism-ai-mcp-server 0.2.0

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

Source distribution (sdist)

Source distribution for prism-ai-mcp-server 0.2.0
File Size Uploaded Provenance Actions
prism_ai_mcp_server-0.2.0.tar.gz 14.2 kB With provenance Details for prism_ai_mcp_server-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for prism-ai-mcp-server 0.2.0
File Interpreter ABI Platform Actions
prism_ai_mcp_server-0.2.0-py3-none-any.whl Python 3 none any Details for prism_ai_mcp_server-0.2.0-py3-none-any.whl

Total release size: 30.4 kB

Release files / prism_ai_mcp_server-0.2.0.tar.gz

Download URL prism_ai_mcp_server-0.2.0.tar.gz
Size 14.2 kB
Tags Source
SHA-256 checksum
How to use checksums
630062897824d5a944366c22d77173dae08a255a56c5bda592389bae5e337ee7
BLAKE2b-256 checksum
How to use checksums
8b8c67c9bb9d1075becf3229ed10fe5de9e21db9bbcd84cbf4c860760a49b363
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / prism_ai_mcp_server-0.2.0-py3-none-any.whl

Download URL prism_ai_mcp_server-0.2.0-py3-none-any.whl
Size 16.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
c5344c24c49c486c5a102e4f24d407bedc7b0f61ffa11a5f25f6c2699fab52aa
BLAKE2b-256 checksum
How to use checksums
68f855a3aba3c529313a9f7e59ae30c7e6725b0462ce04a51e1d109597bfe05f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

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.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for prism-ai-mcp-server 0.2.0

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.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for prism_ai_mcp_server-0.2.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

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.

Release history Release notifications | RSS feed

This release

0.2.0 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page