HTTP MCP servers

HTTP MCP servers can expose many tools through one endpoint. Stashbase lets an agent profile associate an HTTP MCP server with a credential binding and restrict the tools the agent can discover and call.

MCP tool rules apply to HTTP transports, including Streamable HTTP, in both local and remote Agent Proxy sessions. Stdio MCP servers are not covered because their JSON-RPC traffic does not pass through the HTTP proxy.

Configure a server

Define each server at the profile root with [mcp_servers.<name>]:

[secrets.LINEAR_API_KEY]
env = "LINEAR_API_KEY"

[[secrets.LINEAR_API_KEY.rules]]
effect = "allow"
hosts = ["mcp.linear.app"]
methods = ["GET", "POST"]
paths = ["/mcp"]

[mcp_servers.linear]
url = "https://mcp.linear.app/mcp"
binding = "LINEAR_API_KEY"
allow_tools = ["search_issues", "get_issue"]

The HTTP rule and the MCP server entry protect different parts of the request. The binding's hosts or rules authorize endpoint access and credential injection; the MCP entry authorizes tool use. Defining mcp_servers.* does not by itself authorize a credential-bearing HTTP request.

Each server supports these settings:

When a server uses a different authentication scheme than the binding's normal HTTP destinations, override it on the server:

[mcp_servers.example]
url = "https://mcp.example.com/mcp"
binding = "SHARED_TOKEN"
header = "X-API-Key"
value_template = "{value}"

Tool authorization

allow_tools defaults to deny-all when it is omitted or empty. Set allow_tools = ["*"] to explicitly allow every tool returned by the server. deny_tools takes precedence, so it can remove selected tools from a wildcard allowlist.

The Agent Proxy enforces the policy at both protocol boundaries:

• It filters unauthorized tools from tools/list responses, so they are not visible to the agent.
• It rejects unauthorized tools/call requests, including calls made directly by a client.

Keep the HTTP credential policy and MCP tool policy narrow. A binding must authorize the MCP endpoint through its hosts or rules; the server entry only controls MCP tool access.

Inspect and verify tools

Inspect a configured server without invoking a tool:

stashbase agent mcp tools --profile coding --server linear

This performs the MCP handshake and tools/list, then reports the server's tools and the profile's allow/deny decisions.

Check one tool against the local policy without contacting the server or invoking the tool:

stashbase agent mcp check --profile coding --server linear --tool delete_issue

The result explains whether the decision came from allow_tools, deny_tools, or the default deny-all behavior.

Verify that configured tool names still exist on the server:

stashbase agent mcp verify --profile coding --server linear

This contacts the server, compares the configured names with tools/list, and exits unsuccessfully when a configured tool is missing. Add --remote to tools or verify when the binding should be resolved by the remote Agent Proxy.

To interactively fetch a server's tools and save a selected allowlist to a writable repository profile, use:

stashbase agent mcp configure --profile coding --server linear

The command can allow all tools explicitly or save a selected allowlist while preserving the profile's existing credential rules and comments. Global profiles must first be copied to a writable repository profile or passed with --policy-file.

Local and remote sessions

MCP rules work in normal local runs and remote runs:

stashbase agent run --profile coding -- codex
stashbase agent run --remote --profile coding -- codex

In a local run, the local Agent Proxy enforces the MCP JSON-RPC request and response. In a remote run, the same rules are sent to and enforced by the remote Agent Proxy. Personal Credential bindings require --remote.

Audit metadata

MCP policy decisions are included in Agent Proxy audit metadata. Events can include the configured MCP server and tool name where available, alongside the normal destination and binding metadata. Logs never include secret values, placeholders, headers, request bodies, URLs, or command arguments. See Agent logs.

See Profile configuration for the complete profile settings and Credential rules for host, method, and path matching.