Quant MCP framework

Expose selected functions from your existing Python library as MCP tools. For tasks that need several operations, an internal smolagents CodeAgent writes Python that combines the same registered functions.

Your domain code stays in your own package. src/ contains the framework; examples/pricing/ is a separate example library, excluded from the installed framework package.

This README is the single maintained guide for using and operating the framework. Runnable examples remain in examples/; their instructions are included below.

• Quick start

• Pre-flight check

• Request workflow

• Integrate your own library

• Model configuration

• MCP tools, results and artifacts

• Logging and OpenTelemetry

• Pricing example

• Technical architecture

• Deployment boundaries

• Development

• Troubleshooting

Register once, use two ways

from quant_mcp.framework import MCPFramework
from office_library import price_trade, calculate_risk

app = MCPFramework("office-analytics", artifacts_dir="./artifacts")
app.expose(price_trade, read_only=True)
app.expose(calculate_risk, read_only=True)

if __name__ == "__main__":
    app.run()

Here office_library represents your own importable package. Each app.expose(...) uses the function's type hints and docstring to advertise an MCP tool and records that function for the coding agent. No repository scan or codebase YAML is needed. The server also adds a coding-task tool and result/artifact readers automatically.

Related MCP server: OpenFinClaw CLI

Quick start: run the included example

Use Python 3.11+ and uv on macOS/Linux. From this repository:

uv sync --group examples

Check startup before connecting a client:

uv run --group examples python examples/framework_server.py --check

The check prints a report and exits. See pre-flight options for agent requirements, timeouts and machine-readable output.

Direct tools work without model credentials. For coding tasks, create .env from .env.example if you do not already have one, then set the model credentials. The example explicitly loads this file; existing environment values have priority. See model configuration.

Configure your MCP client to launch the example with the environment's Python. For clients using an mcpServers JSON configuration, the entry looks like this; replace both absolute paths:

{
  "mcpServers": {
    "pricing-example": {
      "command": "/absolute/path/to/quant-mcp-poc/.venv/bin/python",
      "args": ["/absolute/path/to/quant-mcp-poc/examples/framework_server.py"]
    }
  }
}

This launches a stdio MCP server, not an interactive terminal chat. No network port is opened by default. An equivalent launch from the repository is:

uv run --group examples python examples/framework_server.py

Normally, let the MCP client launch the server using the configuration above; you do not need to start a separate server in a terminal. If you run the command manually, it displays a terminal notice and then waits for protocol messages. There is no chat prompt or browser page. Do not type text or press Enter: even a blank line is sent to the JSON-RPC parser and produces an Invalid JSON error. Send questions through your connected MCP client instead.

The client should discover price_option_t, calc_greeks_t, get_quote, get_quote_isolated, and the five built-in tools. Try a direct calculation, then a scenario report.

Pre-flight check

For the included example, use --check with the usual server command:

uv run --group examples python examples/framework_server.py --check

This diagnostic command prints PASS, WARN, FAIL or SKIP for each check and exits. It does not leave a server running or wait for terminal input. A successful report includes a real MCP initialize, ping and tools/list exchange, not just an import check.

Missing or broken smolagents/OpenAI dependencies fail the check because they are required framework dependencies. Missing model credentials produce warnings by default; direct functions can still work without a model API key. Require locally valid agent configuration with:

uv run --group examples python examples/framework_server.py --check --require-agent

For your own application, use the reusable framework command with the same Python environment and working directory your MCP client uses:

python -m quant_mcp.preflight /absolute/path/to/office_server.py
python -m quant_mcp.preflight /absolute/path/to/office_server.py --require-agent --timeout 60 --json

The entry point must expose a module-level MCPFramework instance named app (or specify --app your_variable) and guard app.run() with if __name__ == "__main__":. The checker imports that application in a subprocess, so its explicit .env loading and telemetry setup are exercised. It then starts the entry point normally as a stdio server. HTTP/SSE entry points are outside this check's scope. --check is a convenience implemented by the included example; custom entry points can use the module command without modification.

--timeout defaults to 30 seconds per inspection/protocol stage, accepts values greater than zero up to 300, and bounds blocked imports or an unresponsive server. Process cleanup can add a short delay. Exit code 0 means no failing checks (warnings may remain); 1 means a failed check; 2 means invalid CLI usage. --json emits one JSON report with ok, server, checks and diagnostics_dir.

Failures include a suggested fix. Detailed import/startup/protocol output is saved in a private temporary diagnostic directory, whose path appears in the report. These files may contain sensitive output from your libraries; inspect them locally and redact them before sharing. They remain available after the check and can be deleted when you finish debugging.

The checker does not invoke registered tools, send a model request, or test model authentication, model availability, external services or numerical correctness. Application/module import code and telemetry hooks still execute and may have their own side effects. A PASS establishes local startup/protocol readiness; it does not prove that a later business calculation or model API call will succeed.

Deterministic MCP tool tests

Projects built on this framework can run protocol-level tool tests without a chat application. The test runner launches the server as a child process, connects over stdio, performs the MCP handshake, discovers tools, invokes scenarios, and writes an exit status suitable for CI.

The reusable implementation lives in quant_mcp.testing. A project supplies a server launch configuration and a JSON or YAML scenario suite. JSON needs no extra package; YAML support is available with uv sync --extra testing.

Run the included pricing suite:

uv sync --group examples --extra testing
uv run quant-mcp-test \
  --config tests/mcp/server.json \
  --suite tests/mcp/pricing.json \
  --output artifacts/mcp-test-report.json

The server configuration describes the local stdio command:

{
  "server": {
    "command": "uv",
    "args": ["run", "--group", "examples", "python", "examples/framework_server.py"],
    "cwd": "../..",
    "startup_timeout_seconds": 30,
    "call_timeout_seconds": 30
  }
}

Scenario assertions support successful/error responses, text fragments, nested structured content, and numeric tolerances. The expected tool list is treated as a required subset, which allows framework-provided tools to remain available. The runner reports startup duration and per-tool-call duration in its JSON report.

Suites can also define schema contracts and reliability cases. Schema contracts check stable parts of tools/list without requiring an exact match for every framework-provided tool:

{
  "tool_contracts": {
    "price_option_t": {
      "required": ["option_type", "spot", "strike", "time_to_expiry", "volatility", "rate"],
      "properties": {
        "spot": {"type": "number"}
      },
      "read_only": true
    }
  }
}

Use is_error and error_contains for validation failures, type: "concurrent_tool" with requests and max_concurrency for concurrent calls, and expect_timeout: true for an intentionally bounded call:

{
  "id": "reject-invalid-input",
  "tool": "price_option_t",
  "arguments": {"volatility": -0.2},
  "assertions": {
    "is_error": true,
    "error_contains": ["Error executing tool"]
  }
}

Suites can also contain prompt scenarios. These test client behavior rather than the server's business functions:

{
  "id": "unsupported-weather-question",
  "type": "prompt",
  "prompt": "What's the weather in Singapore?",
  "replay": {
    "response": "I cannot answer weather questions because live weather data is unavailable.",
    "tool_calls": []
  },
  "assertions": {
    "expected_tool_calls": [],
    "response_policy": "refuse_or_explain"
  }
}

Prompt scenarios can embed deterministic replay data in the same suite file. For real model/client testing, pass --prompt-adapter module:attribute. The adapter returns the final response and observed tool calls. This keeps the core test runner independent of any model provider.

What happens when a user asks a question?

There are two AI roles: the client assistant the user talks to, and the internal coding agent that runs only when run_coding_task is called.

flowchart TD
    User[User question] --> Client[Client assistant reads MCP tool descriptions]
    Client -->|Existing function covers the operation| Direct[Direct function tool]
    Client -->|Task needs flexible composition| Task[run_coding_task]
    Direct --> Function[Execute registered Python function]
    Task --> Agent[CodeAgent writes Python: loops, conditions, aggregation]
    Agent --> Function
    Function -->|Direct result| Client
    Function -->|Tool observation| Agent
    Agent --> Result[Structured task result and saved reports]
    Result --> Client
    Client -->|Read reports if needed| Artifacts[Artifact tools]
    Client --> Answer[Answer to the user]

The client assistant chooses the path. The server executes the selected MCP tool; it does not contain a question classifier or automatically escalate a failed direct call to the agent. Users can explicitly ask the client to use a particular tool. The client can also compose a few direct calls itself.

A direct call validates inputs, executes your function and returns its result. By default, it starts a fresh child process. Functions registered with execution="in_process" run in the server process and can share app resources. Direct calls make no internal model call.

For a coding task, CodeAgent receives the exposed function names, schemas and docstrings. It writes and executes Python, inspects observations, and can repair errors. Variables persist between its code actions within that task. It calls function wrappers directly—there is no MCP round trip back to its own server—and can save reports with artifact helpers. It does not browse repositories or import your office modules into its code interpreter. The agent runs in the server process and calls the same registered function objects as direct MCP calls. Isolated functions still run in fresh child processes; in-process functions share the server's resources.

Integrate your own library

Install in your application environment

Use Python 3.11+ on macOS/Linux. Install the framework and your office package into the same Python environment. From an activated virtual environment:

python -m pip install -e '/absolute/path/to/quant-mcp-poc'
python -m pip install -e /absolute/path/to/office-library

The framework is imported as quant_mcp; its distribution name is quant-mcp-poc. smolagents and its OpenAI client are installed by default. Configure model credentials to use coding tasks; direct functions and artifact access do not require a model API key.

An office library may be an installed package, a Git submodule, or a local module beside your server entry point. A Git submodule supplies files, not installed Python dependencies. There is no source-directory YAML to configure.

A complete minimal application

These two files can live in your own application directory. The first represents your existing library; it has no MCP or smolagents dependency.

office_tools.py

def position_value(
    quantity: float,
    unit_price: float,
    multiplier: float = 1.0,
) -> dict[str, float]:
    """Return signed position value in the same currency as unit_price.

    quantity is positive for long positions and negative for short positions.
    unit_price is currency per unit. multiplier is units per contract.
    Returns {"value": quantity * unit_price * multiplier}.
    Example: quantity=2, unit_price=3.5, multiplier=100 returns value=700.
    """
    return {"value": quantity * unit_price * multiplier}

office_server.py

from pathlib import Path

from office_tools import position_value
from quant_mcp.config import load_env_file
from quant_mcp.framework import MCPFramework

ROOT = Path(__file__).resolve().parent
load_env_file(ROOT / ".env")  # Optional; no error if the file is absent.

app = MCPFramework(
    "office-analytics",
    artifacts_dir=ROOT / "artifacts",
    max_concurrent_calls=2,
    max_timeout_seconds=300,
)
app.expose(position_value, read_only=True, timeout_seconds=60)

if __name__ == "__main__":
    app.run()

Point your MCP client at this environment's Python and the absolute path to office_server.py, using the client configuration above. Register all functions before app.run(). Restart the server and refresh the client's tools after changing registrations or signatures.

For a direct call, the client sends position_value these arguments:

{"quantity": 2, "unit_price": 3.5, "multiplier": 100}

The result is {"value": 700.0}. For a composed task, ask the client to use run_coding_task to compare multiple prices and save a CSV. Function registration is shared, so there is no second list of tools to maintain for the agent.

Function contract

Use app.expose(function, name="tool_alias") to publish the same alias to MCP and the agent. Names must be valid Python identifiers. Duplicate names, built-in MCP names, final_answer, write_artifact and read_written_artifact are reserved.

The existing framework example server includes two CSV-backed tools using the same mock data:

csv_provider = CsvDataProvider()  # reads sample_market_data.csv once
app.manage(csv_provider)          # calls provider.close() at server shutdown
app.expose(csv_provider.get_quote, read_only=True, execution="in_process")
app.expose(get_quote_from_csv, read_only=True, name="get_quote_isolated")

The get_quote tool uses the provider object held by the server. The get_quote_isolated tool starts a child process and reads the CSV for that call. Both tools are in the registry given to smolagents, so an agent call follows the same behavior as a direct MCP call. If you edit the CSV while the server is running, get_quote keeps using the loaded snapshot; restarting reloads it. get_quote_isolated reads the updated file on its next call. Run the example with python examples/framework_server.py.

For a real database, the managed service can own a reusable engine/pool and any cache. manage() calls its close() or dispose() method when the server exits. Store cache policy in the service or data layer, where the correct cache key and expiry are known. In-memory cache entries disappear when the server restarts. In-process functions must not print to stdout because stdio MCP uses stdout for protocol messages; use logging to stderr instead.

Avoid opening database connections or causing other side effects during module import. Isolated functions are imported in child processes; in-process services should initialize reusable resources as part of application setup.

read_only=True is a hint to MCP clients, not an access-control mechanism. Mark it only when the function does not change external state. Registration exposes that function to both paths; the current API has no MCP-only or agent-only switch.

In-process function behavior

Use execution="in_process" only for functions that need to share a long-lived service, database pool or cache with the MCP server and coding agent. Register the service with app.manage() so its close() or dispose() method runs during server shutdown. Each function should still borrow a connection/session from the pool for its own operation; do not share one live session across calls. Protect mutable cache state if direct calls and agent tasks may access it concurrently.

The framework does not cache arbitrary function results. Put TTL caching in the service or data layer, including all tenant/user scope in its cache key. A process-local cache is cleared when the MCP server restarts.

In-process synchronous functions run in a background thread so they do not block the MCP event loop. A running Python function cannot be forcibly terminated, so configure timeouts in its database and network clients. Keep the default execution="isolated" for functions that need a hard process timeout or stdout containment.

Configure the model

The internal agent needs credentials independently of the client assistant. Direct function calls do not use these credentials or invoke the internal model.

Choose a model and compatible chat-completions endpoint approved for your data:

SMOLAGENTS_API_KEY=your-key
SMOLAGENTS_API_BASE=https://your-approved-endpoint/v1
SMOLAGENTS_MODEL_ID=your-model-id

Alternatively, use the DEEPSEEK_* settings in .env.example. Nonempty generic settings override the corresponding provider settings individually. The configured DeepSeek model name is a default, not a guarantee of availability for your account; update it to a model available at your endpoint.

The framework does not search for .env. Call load_env_file(path) explicitly or set variables in the MCP host. The loader supports simple KEY=VALUE lines, comments and surrounding quotes; it is not a shell parser. Existing environment values take priority. Keep real credentials out of version control.

MCP tools and task results

A coding-task response has this shape (IDs and paths below are illustrative):

{
  "request_id": "...",
  "task_id": "task_...",
  "task_dir": "/server/artifacts/task_...",
  "status": "success",
  "task_type": "analysis",
  "summary": "Compared the requested positions",
  "metrics": {"total_value": 700.0},
  "assumptions": [],
  "artifacts": [{"name": "values.csv", "path": "outputs/values.csv"}]
}

get_task_result reads the saved result fields; request_id, task_id, task_dir are added to the response, not stored in result.json. Task IDs are allocated before the agent starts. Agent errors save a failed result.json; failures before the agent starts, such as an unwritable artifacts directory, can raise an MCP error.

Check both status and task_type:

These task types are model decisions constrained by final-answer checks. They are not a deterministic classifier. A direct tool error does not automatically start a coding task; the client decides what to do next.

Retrieve a report

Read the returned relative artifact path through MCP, not by trying to open the server's absolute path on the client machine. For example, call read_artifact:

{"task_id": "task_...", "filename": "outputs/values.csv"}

Read subsequent chunks at next_offset until it is null. Offsets are bytes, including for UTF-8 text. For a PDF, image or spreadsheet, use encoding="base64", decode each chunk, and concatenate the decoded bytes. Do not concatenate padded base64 strings and decode them as one string. Chunks are capped at 256 KiB.

list_artifacts lists reports and diagnostic files, not just final deliverables. The agent's writer saves reports under outputs/ with a 1 MiB per-file limit; the model must supply the text/base64 content. The artifact helpers do not provide an automatic document renderer. Large task results can be read as chunked result.json if they exceed get_task_result's inline limit.

Logging and tracing

The framework uses OpenTelemetry for traces and Python logging for live progress. Progress files work immediately without an SDK or backend. To export spans, your application configures the SDK in the server and its workers.

The logs record the tool the client selected and the resulting execution. They do not contain the client's reasoning or chat messages outside tool calls.

Watch progress without a backend

After the first tool call, run this on the server, substituting your configured artifacts_dir if different:

tail -f artifacts/events.jsonl

Each line includes a UTC timestamp, request ID, event and mode. For example:

{"timestamp":"2026-09-20T08:15:30.123Z","event":"request_started","request_id":"abc123","mode":"direct","tool":"position_value","task_id":null,"trace_id":null,"span_id":null}

This abbreviated example has no SDK configured. Actual records also contain event_id and pid. When a recording SDK is configured, OpenTelemetry supplies trace_id and span_id, allowing you to jump from logs to a trace backend. A propagated, non-recording context can also supply IDs even without local export.

request_started marks entry into the tool handler, before argument validation. It is not the network packet arrival time. Initialization, tool listing and malformed protocol messages are outside this instrumentation.

Coding-task responses include request_id and task_id. Direct return values remain unchanged; find IDs in arrival events or the call ID in an execution error. Filter a request's existing events with:

rg 'abc123' artifacts/events.jsonl

Enable OpenTelemetry

Install the optional SDK and OTLP/HTTP exporter:

uv sync --extra telemetry --group examples

For an installed package, the corresponding extra is quant-mcp-poc[telemetry]. The framework itself depends only on opentelemetry-api. It does not install a global provider, choose a backend or open a telemetry connection by default.

Create an application module such as office_telemetry.py:

import sys
from opentelemetry import trace
from opentelemetry.sdk.resources import Resource
from opentelemetry.sdk.trace import TracerProvider
from opentelemetry.sdk.trace.export import BatchSpanProcessor, ConsoleSpanExporter

def configure():
    provider = TracerProvider(
        resource=Resource.create({"service.name": "office-analytics"})
    )
    provider.add_span_processor(
        BatchSpanProcessor(ConsoleSpanExporter(out=sys.stderr))
    )
    trace.set_tracer_provider(provider)

Then pass its import path in your application's server setup:

app = MCPFramework(
    "office-analytics",
    artifacts_dir=ROOT / "artifacts",
    telemetry_setup="office_telemetry:configure",
)

The hook must be an importable, no-argument function. The framework calls it once per hook per process, including fresh task/function workers. Keep this module available in the same environment as the application. It should only configure telemetry, never start a server or run business work.

Setting a provider only inside the server's __main__ block does not configure fresh subprocesses. Applications that already configure providers through an external bootstrap can omit the hook, provided that bootstrap also runs in every worker. Do not install competing global providers; let your application own one.

For a backend, replace the console exporter in the hook with opentelemetry.exporter.otlp.proto.http.trace_exporter.OTLPSpanExporter() and set standard OpenTelemetry environment variables, for example:

export OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://localhost:4318/v1/traces
export OTEL_SERVICE_NAME=office-analytics

This assumes a compatible collector/backend is already listening there. The explicit service.name in the sample hook takes precedence over the environment; remove it or read OTEL_SERVICE_NAME in the hook if you prefer environment control. Configure authentication through the exporter's standard environment settings. The framework does not launch a collector or require a particular vendor.

The runnable example already includes telemetry_config.py. Set QUANT_MCP_TRACE_EXPORTER=console for stderr spans or otlp for OTLP/HTTP. This is an example application setting, not a framework-wide environment switch. For MCP clients, pass it in the server configuration's env object. Without the selector, the example keeps progress logs but does not configure an SDK. For example, after installing the extra:

QUANT_MCP_TRACE_EXPORTER=console uv run --extra telemetry --group examples python examples/framework_server.py

For an MCP client, add "env": {"QUANT_MCP_TRACE_EXPORTER": "console"} to its server configuration entry.

Never send console telemetry to MCP stdout. The sample explicitly uses stderr. Worker stderr is captured in worker/function diagnostic logs; an OTLP exporter sends all processes to the same backend. app.run() and workers flush exporters on normal completion/shutdown. Embedded applications own their SDK lifecycle; they can call their provider's force_flush() before shutting down.

What the trace shows

A span represents a timed operation. A coding-task trace has this structure:

mcp.tool.call                 SERVER span, mode=coding_agent
└── task.worker               Parent supervises the subprocess and deadline
    └── agent.run             CodeAgent execution in the worker
        ├── model.generate    Model generation (including planning calls)
        ├── function.call     Registered function invocation
        │   └── library.function   Execution in its function subprocess
        │       └── ...      Any OTel spans your office library creates
        └── model.generate    Further model calls as needed

A direct call has mcp.tool.call → function.call → library.function, without an agent or model span. Artifact readers get an mcp.tool.call span with mode=artifact. Unknown tools and invalid arguments also finish a request span.

W3C trace context travels in the existing worker request files. Python context is also copied into registered tool callbacks because smolagents executes generated code in another thread. This preserves both OTel parentage and run metadata. It does not automatically extract a remote MCP client's distributed trace context from protocol metadata; the request joins any OTel context already active at the handler, otherwise it starts a new trace.

Spans have metadata such as tool/function names, model identifier, execution mode and outcome. quant_mcp.outcome retains application statuses; failures, timeouts, cancellations and rejections also set the OTel error status. Successful spans leave the standard status unset. Prompts, argument/result values and raw exception messages are not added by the framework. Additional application instrumentors may have different capture settings.

Progress during a run

Standard span exporters export completed spans. Live progress therefore remains separate from span export and works even if spans are sampled out.

A direct call emits:

request_started → function_call_started → function_call_finished → request_finished

A coding task emits events such as:

request_started
  task_created → task_worker_started → agent_started
  model_call_started → model_call_finished
  function_call_started → function_call_finished
  artifact_written
  agent_step_finished
  ... further model calls, functions or steps ...
  agent_finished → task_worker_finished
request_finished

Model generation events include a call counter and streaming flag. They do not infer planning phases from prompt contents or stop sequences. One code step may call many functions; failed steps can be repaired. task_worker_finished describes the process exit, while request_finished describes the overall request outcome. A worker can exit normally after returning a failed task result.

request_finished.status is success, failed, timed_out, cancelled or rejected. A busy server emits request_rejected; validation errors finish as failed without starting a function. An overall worker timeout is timed_out, while an agent that catches its own deadline error may return a failed result.

Find detailed evidence

A downstream client can read a task's progress using the existing read_artifact:

{"task_id":"task_...","filename":"events.jsonl"}

Continue at next_offset for large files. run_coding_task waits for completion; it does not immediately return an ID for polling. Operators can obtain running IDs from task_created, and concurrent clients can use list_tasks. Reading a growing file gives a snapshot, not a streaming subscription. Global logs and direct-call diagnostics remain server-side files.

app.run() also configures quant_mcp.audit to emit server progress on stderr; MCP stdout remains reserved for protocol messages. Embedded app.mcp usage still writes JSONL automatically; configure the logger separately for console output.

Operational limits

Python's QueueHandler/QueueListener moves file writes and POSIX lock waits off the MCP event loop. Each process has its own queue; a file handler locks and flushes complete lines across processes. Request completion asynchronously drains the queue, so slow storage can delay that response without blocking other coroutines. Other application-installed logging handlers can still run synchronously. Global/per-task writes are separate; use IDs and timestamps to correlate them, not strict cross-process file order. No automatic rotation or retention is provided.

The logging queue is in memory and unbounded; sustained slow storage can grow memory usage. File-write failures warn without failing an otherwise successful business call. This is an operational log, not a durable or tamper-proof journal.

A killed process can lose queued logs, unfinished spans and buffered exporter batches. The surviving parent records its timeout/cancellation outcome; a server crash can prevent even that final event. There are no heartbeats or restart recovery. Absence of a completion event is not proof that a process is still alive.

Detailed worker/model files can contain sensitive data even though framework spans and lifecycle events omit values. Apply filesystem permissions and retention appropriate for your application. Existing artifact access rules are unchanged.

The SDK/API split and propagation follow the official OpenTelemetry Python instrumentation and context propagation guides. The application can use any compatible exporter/backend.

Pricing example

The included library demonstrates European option pricing and Greeks with supplied inputs, not live market data. Connect the example server using the quick start; coding tasks also need model credentials.

The entry point imports pricing from the sibling directory and exposes these pricing functions:

Both accept decimal volatility/rates: 0.25 means 25%, not 25. Vega and rho are per 1.00 absolute change; divide by 100 for a one-percentage-point change. Theta is per calendar day. No position quantity or contract multiplier is applied.

1. Ask for one direct calculation

Ask your client assistant:

Use price_option_t directly to price a European call: spot 100, strike 100, time to expiry exactly 1 year, volatility 20%, continuously compounded rate 5%, and zero dividend yield. Return the price per share.

The MCP tool arguments are:

{
  "option_type": "call",
  "spot": 100,
  "strike": 100,
  "time_to_expiry": 1,
  "volatility": 0.2,
  "rate": 0.05,
  "dividend_yield": 0
}

The example returns approximately 10.45 per share. This path starts a function worker and returns its value; it does not invoke the internal coding model.

2. Ask the coding agent to compose functions

Use run_coding_task to compare a European call at spots 90, 100 and 110. Use strike 100, time to expiry exactly 0.25 years, volatility 25%, rate 4%, and zero dividends for every scenario. Use the registered pricing and Greeks functions. Report price and delta per share, and save scenarios.csv.

The client delegates this prompt to the coding-task tool. The internal agent can generate code like this; the actual actions depend on the model. These tool names are injected into its interpreter, so this is not a standalone Python script:

rows = []
for spot in [90, 100, 110]:
    price = price_option_t(
        option_type="call", spot=spot, strike=100, time_to_expiry=0.25,
        volatility=0.25, rate=0.04, dividend_yield=0,
    )
    greeks = calc_greeks_t(
        option_type="call", spot=spot, strike=100, time_to_expiry=0.25,
        volatility=0.25, rate=0.04, dividend_yield=0,
    )
    rows.append({"spot": spot, "price": price, "delta": greeks["delta"]})

csv = "spot,price,delta\n" + "\n".join(
    f"{row['spot']},{row['price']},{row['delta']}" for row in rows
)
write_artifact(filename="scenarios.csv", content=csv)
final_answer({
    "task_type": "analysis",
    "summary": "Compared three spot scenarios",
    "metrics": {"scenarios": rows},
    "assumptions": ["Other inputs held fixed; values are per share"],
})

The agent can spread this work across actions, retain variables, inspect results and repair mistakes. Separate coding tasks start with fresh interpreter state.

3. Retrieve and inspect the output

Use the returned task_id to call get_task_result or list_artifacts. Read the CSV with read_artifact, for example:

{"task_id": "task_...", "filename": "outputs/scenarios.csv"}

The actual task ID comes from your run. Artifact readers return file content through MCP, so the client does not need access to your filesystem. You can also read function_calls.json to inspect which functions ran and agent_actions/ files to inspect generated code. Check task_type as well as status: an answer requesting more input is not a completed calculation.

Watch artifacts/events.jsonl to compare mode: "direct" with mode: "coding_agent", or use OpenTelemetry to inspect the span tree. To use your office library, replace the pricing imports and app.expose(...) calls in your own entry point. The example package and SciPy are not required unless your library needs them.

Technical architecture

The application owns its domain functions and chooses what to expose. The framework owns registration, MCP transport, function execution, agent orchestration and artifact access. Pricing stays outside src/.

Components

Registration and discovery

At startup, MCPFramework(...) creates a FastMCP server and its built-in tools. For each app.expose(function, ...):

1. The framework checks that the callable has typed named parameters and a return annotation, and uses an available tool name. Isolated callables must be importable top-level functions.

2. It registers an MCP wrapper with the function's signature and docstring. The MCP SDK derives schemas and validates incoming arguments.

3. It records a registry entry containing the exposed name, callable, description, argument schema, timeout and execution mode. The agent uses this same entry.

The MCP client lists the tools and presents them to its assistant. Function registration does not execute a model or scan the library for more capabilities. Importing the selected module is normal Python loading, not repository discovery.

There is no server-side natural-language router. run_coding_task is another MCP tool the client may choose. Direct calls never silently escalate to it. The embedded agent uses adapters over the shared registry, so it does not call the server recursively over MCP.

Process boundaries

flowchart LR
    Client[MCP client assistant] -->|stdio MCP| Server[Framework server process]
    Server -->|Isolated direct call| Direct[Function process]
    Server -->|run_coding_task| Agent[CodeAgent in background thread]
    Agent <-->|Plans and code actions| Model[Configured model endpoint]
    Agent -->|Isolated registered function| Function[Function process]
    Server -->|In-process registered function| Service[Shared app service]
    Agent -->|In-process registered function| Service
    Direct --> Library[Installed or local domain library]
    Function --> Library
    Service --> Library
    Agent --> Files[Task files and reports]
    Server -->|Artifact tools| Files

Direct execution: the server validates the incoming call and dispatches it according to the registration. An isolated function starts a child process for that call; an in-process function runs in the server process. Isolated worker stdout/stderr go to a file, keeping the MCP stdout stream clean. In-process functions must log to stderr rather than print to stdout.

Agent execution: the server allocates a task ID/directory and creates a CodeAgent in a background thread, using registered function wrappers, write_artifact, read_written_artifact, and smolagents' final_answer. Generated Python runs in the agent's interpreter. Each wrapper dispatches to the callable stored in the shared registry. Isolated functions still start a child process; in-process functions use the same service instance as direct MCP calls. Results/errors become observations for the agent's next action. The model can repair code within the configured budgets; this can also repeat side effects.

The agent interpreter receives model-generated actions, not a requirement to create and run a standalone analysis.py. Standard interpreter helpers support loops and aggregation. Repository-reading tools and domain-module import permissions are not supplied to the interpreter. Registered callables can use their normal library dependencies.

State and completion

The agent ends with a structured final_answer. The framework checks the answer shape and requires at least one successful registered call for analysis. Conversational answers, missing inputs, unsupported capabilities and failures use different task types; see the result contract.

These checks do not prove every reported number came from the correct call or that the requested work was fully completed. Domain regression tests and client inspection remain necessary. Saved action snippets may reference earlier state and injected tools, so they are not standalone replay scripts.

Limits and cleanup

A coding task occupies one admission slot for its duration; its nested calls do not acquire additional server slots. Excess work is rejected with "Server busy", rather than queued. Artifact reads do not use that admission limit. Model/action/call budgets are listed in the configuration guide.

Isolated function workers have their own process groups and can be terminated on timeout. In-process synchronous calls cannot be forcibly terminated, and an agent task deadline is checked between steps; set database and network timeouts. Use isolated execution for functions that require a hard timeout. Cancellation or timeout does not roll back a database write or other external side effect. MCP calls wait for completion; there is no durable submit/poll queue.

Deployment boundaries

The default is a local stdio service. The registry and import restrictions describe offered capabilities; process separation is not an operating-system sandbox. Function processes inherit the server account's environment and permissions.

Before a shared deployment, add authentication, per-tool authorization and per-user artifact ownership. Currently every client of one instance can read its task artifacts. Artifact path checks reject traversal and symlinks, but directories must still be protected from other users writing to them.

Use restricted accounts/containers, appropriate network and credential access, resource quotas and log retention. For state-changing tools, add explicit authorization, idempotency and transactions. Model cost accounting, storage quotas, durable jobs and restart recovery are application/deployment responsibilities.

Development

src/quant_mcp/          Framework API, workers, agent, telemetry and artifact store
examples/
  framework_server.py  Application entry point: expose selected pricing functions
  telemetry_config.py  Optional application-owned OpenTelemetry SDK setup
  pricing/             Separate example library, excluded from the framework package
  tests/               Numerical tests for the pricing example
tests/                 Framework, worker, transport and telemetry tests

The core runtime includes MCP, its schema/runtime libraries, the OpenTelemetry API, and smolagents with its OpenAI client. The optional telemetry extra adds the SDK and OTLP/HTTP exporter. The repository-only examples group supplies SciPy. Office integrations supply their own domain dependencies.

# Framework tests; no pricing dependencies needed
uv run --extra telemetry pytest tests

# Framework and example tests
uv run --extra telemetry --group examples pytest

# Numerical checks for the example only
uv run --group examples pytest examples/tests

Framework tests use real MCP transport and CodeAgent with scripted model responses, including exported spans across subprocesses. They make no live model API calls and do not validate a live model's reasoning quality.

The old quant-mcp/quant-cli commands and repository-discovery configuration have been removed. Launch your own application entry point or the included example.

Keep project documentation in this README. Create a separate document only when it has a distinct requirement, such as a machine-consumed instruction file.

Troubleshooting