# Connecting to MCP Servers

Weavestream can connect to external MCP (Model Context Protocol) servers as a client. This lets you bring tools and data from any MCP-compatible server directly into Weavestream — making them available to the AI agent in chat and as automatically-polled data sources.

# What Is an MCP Server?

MCP servers are services that expose tools and data through a standardized protocol. They can be local utilities (running on your Mac as a subprocess), remote services (accessible over HTTP), or published packages (installed via npx or uvx). By connecting Weavestream to an MCP server, its tools become available alongside Weavestream's built-in tools.

# Adding an MCP Server

In the sidebar, find the MCP Servers section. Click the + button to open the connection wizard. The wizard walks you through four steps.

# Step 1: Load

Paste one of the following to auto-configure:

A GitHub URL — Weavestream fetches the server's manifest automatically
A JSON config snippet — Paste a pre-built config block
A server URL — For HTTP servers you're connecting to directly

You can also drag and drop a .dxt file, or click Set up manually to configure everything by hand.

# Step 2: Configure

Give the server a name, then configure the connection details based on the transport type.

# HTTP

For servers accessed over a network connection:

Server URL (required) — The full URL of the MCP server (e.g., http://localhost:8080)
Bearer Token (optional) — Leave empty if the server doesn't require authentication. Enter the token if it does.

# stdio

For servers that run as a local subprocess on your Mac:

Command (required) — The executable to run (e.g., npx, uvx, python3)
Arguments — Space-separated arguments passed to the command (e.g., @scope/package-name)
Working Directory (optional) — Required for local projects. Leave empty for published packages installed via npx or uvx.
Environment Variables — Key-value pairs passed to the subprocess. Secret values (like API keys) are stored in your Mac's Keychain.

Weavestream checks whether the required runtimes (Node.js, Python, etc.) are available on your Mac and shows a green checkmark or a warning for each.

# Step 3: Connect

Weavestream attempts to connect and shows a live log of the handshake. Once connected, it displays the number of tools the server offers. If connection fails, an error message and suggestion appear.

# Step 4: Configure Tools

For each tool the server exposes, you choose how Weavestream should use it:

Data Source — The tool is called automatically on a schedule (every 5 minutes, 15 minutes, or 1 hour). Results are stored as items in Weavestream, just like API endpoint data. Choose this for tools that return data you want to browse or analyze over time.
Action Only — The tool is only available for the AI to call on demand during a conversation. It's never polled automatically. Choose this for tools that perform actions or retrieve data in response to specific questions.

Click Done to finish.

# Managing MCP Servers

Connected servers appear in the MCP Servers section of the sidebar. Each shows a status indicator:

Green — Connected
Orange — Connecting
Red — Connection error
Gray — Disconnected

Right-click a server to Edit its configuration or Remove it.

# Editing a Server

The edit sheet lets you update the server name, connection URL or command, authentication credentials, and per-tool settings (role and poll interval). You can also toggle individual tools on or off, or click Reconnect if the connection dropped.

# How the AI Agent Uses MCP Tools

When you select an MCP server in the sidebar (or when its tools are in scope), the AI agent can call them directly during a conversation. The tools appear in the agent's available toolkit alongside Weavestream's built-in tools like search_items and filter_items.

Data Source tools that have been polled also create regular Weavestream items — you can browse, filter, and analyze this data exactly like any other source.

# Authentication & Credentials

Bearer tokens (HTTP servers) are stored in your Mac's Keychain
Environment variable values (stdio servers) are stored in your Mac's Keychain, never in plain text
Credentials are never exposed to the AI — only the tool results are visible

# Connection Reliability

Weavestream automatically reconnects to MCP servers if the connection drops, using an exponential backoff strategy (retrying after 1 second, then 2, 4, 8... up to 30 seconds, for a maximum of 5 retries). If you manually disconnect a server, auto-reconnect is suppressed until you re-enable it.