MCP tools

​

How it fits together

1. The agent lists the MCP server’s URL and, optionally, which of its tools the model may use.
2. A vault credential holds the server’s access token, if it needs one. You attach the vault to the session. The token is never shown to the model.

​

Before you start

• Remote MCP servers are currently blocked on hosted Orca; see the note above.
• Get a token for the MCP server if it requires authentication. An admin stores it in a vault.

​

Example

import os

agents = client.beta.agents
url = "https://mcp.example.com/orders/mcp"

# 1. Store the server's token in a vault.
vault = agents.vaults.create(name="orders")
agents.vaults.credentials.create(
    vault.id,
    name="orders-reader",
    auth={
        "type": "static_bearer",
        "mcp_server_url": url,
        "token": os.environ["ORDERS_MCP_TOKEN"],
    },
)

# 2. Give the agent the server, limited to one tool.
agent = agents.create(
    model=os.environ["ORCA_MODEL"],
    name="orders",
    tools=[
        {
            "type": "mcp",
            "server_label": "orders",
            "transport": {"type": "http", "server_url": url},
            "allowed_tools": ["lookup_order"],
        }
    ],
)

# 3. Attach the vault to the session that uses the agent.
session = agents.sessions.create(
    agent_id=agent.id,
    environment={"type": "none"},
    vault_ids=[vault.id],
    input="Look up order-42",
)

​

The tool definition

​

What happens at runtime

• At session start, Orca connects to each MCP server and fetches its tool list. If a server is unreachable, or a credential it needs is missing, session creation fails with an error instead of starting a broken session.
• During a turn, each call is recorded as an mcp_call item in the history, with its arguments and result. Use these to audit what the agent did.
• The calls come from the Orca server by default, not from your application. To make them from inside the session’s sandbox instead, for example to reach a server that only the sandbox’s network can see, set "connection_origin": "environment" on the tool. That requires a session with a sandbox.

​

Keep it safe

• Allow only what is needed. Use allowed_tools, and prefer read-only tools. Add write tools only when the task requires them.
• Treat results as untrusted. An MCP server can return any text, including text that tries to give the model new instructions. Do not give an agent that reads untrusted content access to dangerous tools.
• Scope credentials tightly. Each credential works only for its exact server URL. Use tokens with the smallest permissions the server supports.

​

Troubleshooting