Skip to content

alpineagents

Use MCP servers

TGoddessana/alpineagents

Use MCP servers¶

Give an Agent the tools of an MCP server. Install the extra first:

pip install "alpineagents[mcp]"

Add a server¶

Put the server in tools= like any other tool:

import os

from alpineagents import MCP, Agent

github = MCP(
    "npx -y @modelcontextprotocol/server-github",
    name="github",
    env={"GITHUB_TOKEN": os.environ["GITHUB_TOKEN"]},
)
linear = MCP(
    url="https://mcp.linear.app/mcp",
    name="linear",
    headers={"Authorization": f"Bearer {os.environ['LINEAR_API_KEY']}"},
)

agent = Agent(model="claude-sonnet-5", tools=[github, linear.list_issues])

Argument	Meaning
`command` (first argument)	The command that starts a local server. `env=` sets extra environment variables. The server does not get your full environment
`url=`	The URL of a remote server. `headers=` adds HTTP headers
`name=`	Required. The model sees each tool as `{name}__{tool}`, for example `github__create_issue`

Pass exactly one of command, url= and server=. server= takes an in-process server, for tests.

Pick tools¶

Pass	The Agent gets
`github`	Every tool of the server
`linear.list_issues`	One tool
`linear["list-issues"]`	One tool, for a name that is not a Python identifier

During a run, agent.tool_map["github__create_issue"] is the connected tool (MCPTool). Its hints (read_only, destructive, idempotent, open_world) come from the server's tool annotations. They are what the server says about itself, so do not trust them more than the server (Write permission rules).

Connections¶

agent.run connects the servers at the start and disconnects them at the end.
with agent: (or async with agent:) keeps them connected across several runs.
Agents and concurrent runs that use the same MCP object share one connection.
A tool name that collides with another tool, or a picked tool the server does not have, raises ValueError when the server connects, before the first think.

Results¶

The server's text comes to the model as text, and its PNG, JPEG, GIF and WebP images as images (see Tools on objects and from data). Other content, such as audio or an SVG image, becomes a short note saying it was not shown.

Errors¶

Situation	What happens
The server returns an error for a call	The model gets it as an error result (`outcome.kind == "error"`). The run continues
The connection fails or is lost	`MCPConnectionError` is raised