# Integration Targets

These are the main ways to integrate `pyro-mcp` into an LLM application.

## Recommended Default

Use `vm_run` first.

That keeps the model-facing contract small:

- one tool
- one command
- one ephemeral VM
- automatic cleanup

Only move to lifecycle tools when the agent truly needs VM state across multiple calls.

## OpenAI Responses API

Best when:

- your agent already uses OpenAI models directly
- you want a normal tool-calling loop instead of MCP transport
- you want the smallest amount of integration code

Recommended surface:

- `vm_run`

Canonical example:

- [examples/openai_responses_vm_run.py](/home/thales/projects/personal/pyro/examples/openai_responses_vm_run.py)

## MCP Clients

Best when:

- your host application already supports MCP
- you want `pyro` to run as an external stdio server
- you want tool schemas to be discovered directly from the server

Recommended entrypoint:

- `pyro mcp serve`

Starter config:

- [examples/mcp_client_config.md](/home/thales/projects/personal/pyro/examples/mcp_client_config.md)
- [examples/claude_desktop_mcp_config.json](/home/thales/projects/personal/pyro/examples/claude_desktop_mcp_config.json)
- [examples/cursor_mcp_config.json](/home/thales/projects/personal/pyro/examples/cursor_mcp_config.json)

## Direct Python SDK

Best when:

- your application owns orchestration itself
- you do not need MCP transport
- you want direct access to `Pyro`

Recommended default:

- `Pyro.run_in_vm(...)`

Examples:

- [examples/python_run.py](/home/thales/projects/personal/pyro/examples/python_run.py)
- [examples/python_lifecycle.py](/home/thales/projects/personal/pyro/examples/python_lifecycle.py)

## Agent Framework Wrappers

Examples:

- LangChain tools
- PydanticAI tools
- custom in-house orchestration layers

Best when:

- you already have an application framework that expects a Python callable tool
- you want to wrap `vm_run` behind framework-specific abstractions

Recommended pattern:

- keep the framework wrapper thin
- map framework tool input directly onto `vm_run`
- avoid exposing lifecycle tools unless the framework truly needs them

Concrete example:

- [examples/langchain_vm_run.py](/home/thales/projects/personal/pyro/examples/langchain_vm_run.py)

## Selection Rule

Choose the narrowest integration that matches the host environment:

1. OpenAI Responses API if you want a direct provider tool loop.
2. MCP if your host already speaks MCP.
3. Python SDK if you own orchestration and do not need transport.
4. Framework wrappers only as thin adapters over the same `vm_run` contract.