Connect MCP servers to Polyaxon workflows

An MCP server can give an assistant a consistent interface to a useful platform operation: submit an evaluation, inspect its status, or retrieve a sanitized report. The important design choice is what that interface permits—not simply whether the assistant can call it.

For Polyaxon, start with a small application-owned adapter around documented client operations. This is an integration pattern, not a claim that Polyaxon includes a native MCP server.

Keep the protocol and platform roles separate

The MCP architecture separates a host, its client connections, and servers exposing tools, resources, and prompts. The protocol supplies a shared interaction model; your server still needs to implement the requested operation and its access checks.

A Polyaxon adapter might expose three tools:

Avoid a first version that accepts arbitrary Polyaxonfiles, queue names, or credentials from the model. A narrow contract is easier to authorize and evaluate.

Resolve identity before dispatch

Authenticate the caller using the transport and identity system selected for your MCP deployment. Then map that identity to permitted Polyaxon projects and operations in trusted server code.

The model should not choose a more privileged project by changing a tool argument. Resolve human-friendly dataset aliases to approved versions, reject unknown fields, and cap input size before creating a run.

Use the RunClient interface to submit a reviewed component or inspect its execution. Scope the adapter's platform credentials to the work it is intended to perform. Do not forward unrelated caller tokens into the workload.

Use asynchronous results for substantial work

An evaluation may wait for capacity or take several minutes. Return an application request identifier after successful submission, and let a separate tool inspect progress. This avoids tying a long-running job's lifecycle to one client connection.

Persist the association between the request and run UUID. If the connection drops after submission, a retry should find the existing request rather than create duplicate work. Implement that deduplication in the adapter's durable request store.

Treat Polyaxon terminal status and evaluation quality separately. A job can complete successfully while reporting that a candidate missed the quality threshold. Decide whether your evaluator should exit unsuccessfully for that condition or return a separate promotion decision.

Expose evidence instead of raw execution surfaces

Use tracking and artifacts to preserve the evaluation inputs, metrics, and report. The MCP result can summarize those records without copying a large or sensitive artifact into the model context.

Treat report text and tool output as untrusted content. A retrieved document may contain instructions, but those instructions do not gain authority over the adapter's policy.

If the server itself runs as a Polyaxon service, implement and verify its MCP transport, authentication, and proxy-path behavior in your application. Hosting a service does not automatically make every MCP client compatible.

Follow one request through a local adapter

The repository example connects a local MCP host to the shared exact-match evaluator. Prepare that article's evaluator image, Component Hub version, read-only evaluation-data connection, and fixture files first. Its two-case ticket fixture verifies the integration; it does not measure a live agent's quality.

Clone the examples repository in an operator-controlled location, open the adapter directory, and copy the shared lifecycle helper beside it:

git clone https://github.com/polyaxon/polyaxon-examples.git
cd polyaxon-examples/blog/polyaxon-mcp
cp ../sandbox-lifecycle/lifecycle.py .
cp policy.example.json policy.json

If you already cloned the repository for the evaluator, use its blog/polyaxon-mcp directory and perform the two copy steps there. The example consists of:

• adapter.py: input validation, approved workload mapping, a SQLite request ledger, submission, and status lookup.
• server.py: the two MCP tools.
• policy.example.json: the trusted identity, project, candidate, and dataset mapping; edit your policy.json copy.
• operation.yaml: the registered evaluator reference and a five-minute workload timeout with retries disabled.
• lifecycle.py: the shared run-client constructor with a finite HTTP timeout, copied into this directory by the setup command.
• requests.json: ordered tool-call fixtures and expected outcomes.

Use Python 3.11+, your deployment-compatible Polyaxon client, and the official MCP Python SDK's v2 interface (mcp>=2,<3 with an exact version selected in your lockfile). The example uses MCPServer, typed tools, and the stdio transport described in the SDK server guide. It has been checked against the source interfaces, not executed against a deployment.

Set the organization, existing project, registered component reference, and mounted paths in the policy and operation. Configure POLYAXON_MCP_POLICY with the absolute policy path, POLYAXON_MCP_ACTOR=local-reviewer, and POLYAXON_MCP_STATE with a SQLite file path in a private, persistent directory. Configure the Polyaxon host and scoped credentials through your normal client setup. The MCP host launches python /absolute/path/server.py as a local subprocess.

This setup assigns one identity from operator-controlled process configuration. It does not accept an identity, project, component, or credential from model arguments. The local process and its files must stay outside the agent's writable workspace. A multi-user HTTP server needs authenticated per-request identity, authorization, request-size and rate limits, and an appropriate shared state backend before reusing this design.

The submission tool accepts this request shape; the SDK derives its schema from a strict Pydantic model that forbids extra fields:

{
  "request": {
    "request_key": "review-001",
    "dataset": "tickets-v1",
    "candidate": "agent-v12"
  }
}

The adapter commits the request before calling RunClient.create_from_polyaxonfile(). A successful response contains request_id, submission_state: submitted, and the actual run_uuid. Call evaluation_status with that request_id to inspect the run. Review evaluation/summary.json in Polyaxon for the quality decision; the status tool deliberately does not convert infrastructure success into evaluator acceptance.

The ledger cannot transact atomically with the Polyaxon API. For an uncertain request, an operator can inspect runs tagged mcp-request-<request_id> and reconcile the ledger to the verified run. A missing immediate search result is not proof that submission failed. Preserve the ledger across restarts; deleting it removes duplicate protection and the demonstration budget. For a shared service, replace that fixed budget with your actual admission and retention policy.

This example assumes the operator's identity, project, component, and dataset mappings stay fixed for the ledger's lifetime. Do not reuse that ledger with changed mappings: old request keys and run UUIDs still describe the original work. A production adapter should retain the policy revision and original execution scope with each request, then explicitly reconcile or migrate records when the policy changes. Preserve immutable dataset and component revisions as part of that contract.

Begin with a read-only status tool and one bounded submission path. That gives the team a useful integration with a clear review surface before expanding the available capabilities.