# How Macro's MCP Server Exposes Tool Coverage for External AI Agents

> Macro's MCP server exposes tool coverage via a Streamable HTTP binary. Discover available tools, capabilities, and URLs for external AI agents in this technical guide.

- Repository: [Macro/macro](https://github.com/macro-inc/macro)
- Tags: how-to-guide
- Published: 2026-08-16

---

**Macro's MCP server exposes tool coverage by running a Streamable HTTP binary that returns a dynamically constructed prompt listing available tools, their capabilities, and fully-qualified URLs for cross-referencing Macro items.**

Macro is workspace productivity software that builds document, search, and communication tools. Its **Macro Connect Protocol (MCP)** server enables external AI agents—such as large language models—to discover and invoke Macro's native functionality through a well-defined HTTP interface. This article breaks down exactly how the server advertises its **tool coverage** to authorized callers.

## The MCP Server Architecture

The MCP server is implemented as a standalone Rust service that bridges external AI clients with Macro's internal infrastructure.

### Starting the Streamable HTTP Server

In [`services/mcp_service/src/main.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/main.rs), the server initializes and binds to a configurable address:

```rust
// services/mcp_service/src/main.rs
// Launches the MCP server and logs the listening endpoint
println!("MCP server listening on http://{addr}/mcp");

```

The binary is typically started via the project's `just` runner:

```bash

# Start the MCP server from repository root

just run_mcp_server

```

Once running, the server exposes the `/mcp` endpoint where external agents request tool coverage information.

## Building the Tool Coverage Prompt

Tool coverage exposure happens through a **prompt construction pipeline** that combines static instructions with runtime configuration.

### The Core Handler: [`tool_service.rs`](https://github.com/macro-inc/macro/blob/main/tool_service.rs)

[`services/mcp_service/src/tool_service.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/tool_service.rs) implements the primary request handler. It performs three critical functions:

1. **Extracts the authenticated user** from incoming requests
2. **Supplies a base URL** — the public Macro web-app URL used to construct fully-qualified links
3. **Returns tool coverage instructions** describing which Macro-native tools are available

This handler ensures that every AI agent receives context-specific information tied to the requesting user's environment.

### Composing Instructions in [`prompt/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/prompt/src/lib.rs)

The `crates/prompt` crate assembles the final instruction payload. In [`crates/prompt/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/lib.rs), two key components work together:

- **`MCP_STATIC_INSTRUCTIONS`** — A constant holding the static portion of the prompt, including a description of the available toolset
- **`build_instructions` function** — Interpolates the server's public URL and appends static instructions

```rust
// crates/prompt/src/lib.rs
pub fn build_instructions(base_url: &str) -> String {
    format!("{}\n\nBase URL: {}", MCP_STATIC_INSTRUCTIONS, base_url)
}

```

The resulting prompt tells the AI exactly which tools it can invoke and how to format references to Macro items.

## Declaring Available Toolsets

The specific tools exposed to external agents are enumerated in [`crates/prompt/src/connected_toolsets.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/connected_toolsets.rs). This file defines the **connected toolsets** — concrete integrations that the MCP server advertises.

Typical toolset categories include:

- **`document`** — Creation, editing, and retrieval of Macro documents
- **`search`** — Querying across workspace content
- **`email`** — Message composition and thread management

This list is injected into the generated prompt, giving AI agents a complete inventory of callable capabilities.

## Authentication and Secure Access

Before receiving tool coverage information, external agents must authenticate. The MCP layer implements this through two mechanisms.

### Bearer Token Validation

[`services/mcp_auth_proxy/src/inbound/middleware.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_auth_proxy/src/inbound/middleware.rs) handles OAuth flows and bearer token validation. The proxy sits between external clients and Macro's internal services:

```rust
// services/mcp_auth_proxy/src/inbound/middleware.rs
// Validates Authorization: Bearer <token> headers

```

Only authenticated and authorized agents can reach the `/mcp` endpoint to retrieve tool coverage.

### Configuration and Caching

[`services/mcp_service/src/config.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/config.rs) manages runtime settings including:

- Public base URL for link generation
- Redis connection for session/auth caching
- Server bind address and port

## Link Generation for AI Responses

When AI agents reference Macro items in their responses, they cannot use Macro-specific markup like `<m-document-mention>`. Instead, the MCP server instructs them to use **plain URLs**.

The [`crates/prompt/src/mcp_item_links.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/mcp_item_links.rs) module generates these URLs:

- Converts internal Macro identifiers to public web-app URLs
- Ensures MCP clients render responses as clickable references in the host UI

## Practical Usage Example

### Retrieving Tool Coverage

```bash

# Query the MCP endpoint for available tools

curl -s http://localhost:8080/mcp \
  -H "Authorization: Bearer $MCP_TOKEN" | jq .instructions

```

Sample response excerpt:

```json
{
  "instructions": "You are an external AI agent. The following Macro tools are available: \
    document, search, email, calendar. Use plain URLs (e.g., \
    https://app.macro.com/doc/123) when referring to Macro items. \
    Base URL: https://app.macro.com"
}

```

### Invoking an Exposed Tool

```python
import requests
import json

BASE = "http://localhost:8080/mcp"
headers = {"Authorization": "Bearer <MCP_TOKEN>"}

# Call a tool documented in the coverage prompt

payload = {
    "tool": "document.create",
    "params": {
        "title": "Q4 Roadmap",
        "content": "Strategic priorities and timelines..."
    }
}

resp = requests.post(
    f"{BASE}/tool",
    json=payload,
    headers=headers
)
print(json.dumps(resp.json(), indent=2))

```

## Key Implementation Files

| File Path | Purpose |
|-----------|---------|
| [`services/mcp_service/src/main.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/main.rs) | Server initialization and HTTP binding |
| [`services/mcp_service/src/tool_service.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/tool_service.rs) | Core handler for tool coverage requests |
| [`services/mcp_service/src/config.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/config.rs) | Runtime configuration (URL, Redis, ports) |
| [`crates/prompt/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/lib.rs) | Prompt assembly with static instructions |
| [`crates/prompt/src/connected_toolsets.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/connected_toolsets.rs) | Enumerated list of exposed toolsets |
| [`services/mcp_auth_proxy/src/inbound/middleware.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_auth_proxy/src/inbound/middleware.rs) | Bearer token and OAuth validation |
| [`crates/prompt/src/mcp_item_links.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/mcp_item_links.rs) | URL generation for AI response links |

## Summary

- **Macro's MCP server** runs as a Streamable HTTP binary in [`services/mcp_service/src/main.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/main.rs), exposing the `/mcp` endpoint for external AI agents
- **Tool coverage** is communicated through a dynamically constructed prompt combining `MCP_STATIC_INSTRUCTIONS` from [`crates/prompt/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/lib.rs) with runtime base URL configuration
- **Available tools** are explicitly declared in [`crates/prompt/src/connected_toolsets.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/connected_toolsets.rs), giving agents a complete capability inventory
- **Authentication** via `services/mcp_auth_proxy` ensures only authorized agents access tool coverage and invocation endpoints
- **Plain URL generation** through [`crates/prompt/src/mcp_item_links.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/mcp_item_links.rs) enables AI responses to reference Macro items with clickable links

## Frequently Asked Questions

### What protocol does Macro use to expose tools to external AI agents?

Macro implements the **Macro Connect Protocol (MCP)**, a Streamable HTTP-based protocol defined in the `services/mcp_service` crate. MCP returns structured prompts describing available tools rather than exposing raw API schemas, making it easier for LLM agents to understand and use Macro capabilities.

### How does an AI agent discover which tools it can call through Macro's MCP server?

The agent sends an authenticated GET request to the `/mcp` endpoint. The server responds with a prompt built by `build_instructions()` in [`crates/prompt/src/lib.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/lib.rs), which includes the enumerated toolsets from [`crates/prompt/src/connected_toolsets.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/connected_toolsets.rs) and instructions on how to invoke them.

### Why does Macro's MCP server use plain URLs instead of native markup in AI responses?

MCP clients cannot render Macro-specific tags like `<m-document-mention>`. The [`crates/prompt/src/mcp_item_links.rs`](https://github.com/macro-inc/macro/blob/main/crates/prompt/src/mcp_item_links.rs) module generates fully-qualified HTTPS URLs (based on the configured base URL from [`services/mcp_service/src/config.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_service/src/config.rs)) that any client can display as standard clickable links.

### What authentication is required to access Macro's MCP tool coverage?

Requests must include a valid `Authorization: Bearer <token>` header. The [`services/mcp_auth_proxy/src/inbound/middleware.rs`](https://github.com/macro-inc/macro/blob/main/services/mcp_auth_proxy/src/inbound/middleware.rs) component validates these tokens against Macro's OAuth infrastructure. Unauthenticated requests are rejected before reaching the tool service handler.