Plexus MCP / Tactus Runtime

Why one tool?

Earlier MCP integrations often exposed every application operation as a separate tool. That works for small systems, but Plexus has a broad surface area: scorecards, scores, feedback, evaluations, reports, datasets, procedures, documentation, budgets, and handles. Loading all of that as individual tool schemas consumes model context on every call, adding latency and cost while displacing the user task and other useful context.

Plexus now exposes a compact gateway instead. The MCP client calls execute_tactus, and the submitted Tactus code composes the plexus APIs it needs for the current task. The assistant writes a small program instead of choosing from a long menu of fine-grained tools.

The gateway also supports progressive disclosure. The base MCP context only needs to describe execute_tactus and the discovery path: use plexus.api.list() to inspect the available API surface, then use plexus.docs.list() and plexus.docs.get{ ... } to load focused docs and examples for the workflow at hand.

This is the same pattern described on the Tactus site: One Tool For Everything.

Runtime model

Inside execute_tactus, plexus is available as an injected global host module. It delegates to Plexus SDK code, services, documentation, task dispatch, and handle storage. The Tactus runtime provides the controlled execution boundary around those calls.

• Use plexus.api.list() to discover namespaces and methods.
• Use plexus.docs.list() and plexus.docs.get{ ... } to read focused docs during the session.
• Use explicit return values when you want a custom result shape.
• Long-running calls can return handles that are polled, awaited, or cancelled later.

Client setup

Configure your MCP client to launch the Plexus wrapper from your local Plexus checkout. Replace the placeholder paths with your Python environment and project path.

{
  "mcpServers": {
    "plexus": {
      "command": "/path/to/python",
      "args": [
        "/path/to/Plexus/MCP/plexus_fastmcp_wrapper.py",
        "--transport", "stdio",
        "--target-cwd", "/path/to/Plexus"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "PYTHONPATH": "/path/to/Plexus"
      }
    }
  }
}

Credentials are loaded from your Plexus environment and config files. Keep API keys on the host side; they are not passed into the Tactus snippet.

Start with discovery

When unsure what the runtime supports, ask Plexus from inside the runtime instead of guessing tool names.

return {
  apis = plexus.api.list(),
  docs = plexus.docs.list(),
  overview = plexus.docs.get{ id = "mcp.execute-tactus-overview" },
}

Common examples

Inspect a score by scorecard and score identifiers:

return plexus.score.info{
  scorecard_identifier = "Quality Assurance",
  score_identifier = "Compliance",
}

Combine feedback summary and item search in one call:

local summary = plexus.feedback.alignment{
  scorecard_name = "Quality Assurance",
  score_name = "Compliance",
  days = 30,
  output_format = "json",
}

local false_negatives = plexus.feedback.find{
  scorecard_name = "Quality Assurance",
  score_name = "Compliance",
  initial_value = "No",
  final_value = "Yes",
  limit = 5,
  days = 30,
}

return {
  summary = summary,
  false_negatives = false_negatives,
}

Async handles and budgets

Evaluations, reports, and procedures can be long-running. Use async = true to dispatch the work and return a handle. Include an explicit child budget so background work remains bounded.

local handle = plexus.evaluation.run{
  scorecard_name = "Quality Assurance",
  score_name = "Compliance",
  n_samples = 200,
  yaml = true,
  async = true,
  budget = {
    usd = 1.0,
    wallclock_seconds = 900,
    depth = 1,
    tool_calls = 20,
  },
}

return {
  handle_id = handle.id,
  status = handle.status,
}

Later, use the handle APIs from another execute_tactuscall:

return plexus.handle.await{
  id = "<handle-id>",
  timeout = "PT10M",
}

Safety contract

• The MCP surface stays small: clients only need to know execute_tactus.
• The runtime returns structured envelopes with success, value, error, cost, trace, partial, and API-call data.
• Destructive operations request human approval before committing changes.
• Traces and handles let operators inspect what happened and resume long-running work.
• Plexus keeps credentials, SDK implementation, policy, and persistence on the trusted host side.

Troubleshooting

• If the MCP client cannot connect, verify the Python path, wrapper path, --target-cwd, and PYTHONPATH.
• If a Plexus call fails, inspect the returned structured error and trace ID before retrying.
• If a snippet needs a capability you cannot find, call plexus.api.list() and then read the relevant docs with plexus.docs.get{ id = "..." }.