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, thentools/listandtools/call, each carrying its version and client capabilities inparams._meta. - Handshake (
2025-11-25,2025-06-18,2025-03-26,2024-11-05):initialize,notifications/initialized(answered 202),ping,tools/listandtools/call, for clients that always open withinitialize, such as Codex. No session id is issued, so every request stands alone. An unknown requested revision is answered with2025-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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.