Tools and MCP

Choose the execution boundary before declaring a tool. A local Python function, an HTTP service and a provider-hosted MCP server have different callers, authentication and enforcement. MCP is optional.

Start Here

First complete a provider-only workflow. Add one read-only tool and check its permissions before adding more capabilities. From that supplied workspace:

actspan init workspace.yaml
actspan validate workspace.yaml
actspan preview workspace.yaml

Expected static result: these commands inspect declarations and available configuration. They do not start an unspecified server, prove DNS/TLS/authentication, discover every remote tool or establish successful tool execution. Use the complete supplied fixture and live read/denial checks for your chosen topology.

Use the function-tool reference, qualified framework MCP example, or MCP setup guide for the selected path. A shared server contract does not make provider request schemas interchangeable.

Actspan Registry Shape

This is a configuration excerpt, not a downloadable server or independently qualified end-to-end example. Replace the endpoint with your reviewed service and supply its token privately:

mcpServers:
  docs:
    transport: streamable-http
    endpoint: ${DOCS_MCP_SERVER_URL}
    headers:
      Authorization: "Bearer ${DOCS_MCP_TOKEN}"
    allowed_tools: [search]
tools:
  - name: docs_search
    kind: mcp
    server: docs
    tool: search

validate checks declared server references and the selected allowlist. The integration compiles references according to the selected provider/runtime; that does not guarantee one transport or authentication shape works across all providers. Keep the pinned runtime and its fixture together.

Provider-Native YAML Shapes

OpenAI (Responses API)

Hosted reference only. OpenAI makes the MCP connection from its own infrastructure. Set REMOTE_MCP_SERVER_URL to a reviewed HTTPS endpoint reachable by OpenAI; your laptop's 127.0.0.1 is not that endpoint. No tunnel support is implied. This excerpt assumes an existing provider and prompt:

tools:
  - type: mcp
    server_label: approved_search
    server_url: ${REMOTE_MCP_SERVER_URL}
    authorization: ${REMOTE_MCP_TOKEN}
    allowed_tools: [search]
    require_approval: never

The never setting concerns the provider's MCP approval protocol for this read-only reference. It is not an Actspan kind: approval checkpoint or a grant of permission to perform arbitrary writes. The native hosted path remains an assisted qualification guide; local framework MCP success does not qualify it. See OpenAI's hosted MCP contract.

Anthropic (Messages API)

The installed schema accepting mcp_servers does not establish a qualified hosted MCP connection. The old server_name/config.token excerpt was an Actspan-style declaration, not a verified native Messages payload; do not copy it as one. The current payload builder forwards server entries, so do not assume it translates aliases or adds required toolsets/beta headers.

Before using this path, request the pinned integration's complete fixture: server connection type/name/URL, authorization field, required beta selection and toolset configuration. Compare its emitted request with the official Claude MCP contract, then qualify a harmless read and denied action. No live Anthropic hosted MCP qualification is claimed here. Client-side Claude function tools and local framework MCP are separate integrations.

Running MCP Servers

Use the start command and dependencies supplied by your chosen example. This reference does not provide a Node dist/server.js project or a generic Python server package. A loopback URL is appropriate only when the actual caller is local and can reach it. A hosted provider needs the reviewed remote endpoint.

Best Practices

• Keep tools narrow, authenticated and bounded in the service itself.
• Configure tokens through the selected provider's documented fields; a generic config object is not a universal authentication mapping.
• Verify allowed and refused tool paths using backend evidence.
• Retain server, client, provider/model and adapter versions with the results.

Troubleshooting

For connection errors, identify where the client executes, then check URL, TLS and authentication from that boundary. For unwanted tool selection, review tool descriptions and the provider's tool_choice settings. For concurrent calls, check a separate provider-specific parallel-call setting, such as OpenAI's parallel_tool_calls, and confirm the integration honors it. Selection and concurrency are different controls.