MCP Integration

Model Context Protocol (MCP) allows Alma to integrate with external services and tools through a standardized interface.

What is MCP?

MCP is an open protocol that enables:

• Tools: Additional capabilities beyond built-in tools
• Resources: Access to external data sources
• Prompts: Pre-configured prompt templates

MCP Marketplace

Alma includes a marketplace of pre-configured MCP servers:

1. Go to Settings → MCP Servers
2. Click Marketplace
3. Browse available servers
4. Click Install to add a server

Popular MCP Servers

Server	Description
Brave Search	Web search via Brave API
GitHub	Repository management
Slack	Workspace messaging
Filesystem	Extended file operations
Memory	Persistent knowledge base

Adding MCP Servers

From Marketplace

1. Find the server in the marketplace
2. Click Install
3. Configure required parameters
4. Server starts automatically

Manual Configuration

1. Go to Settings → MCP Servers
2. Click Add Server
3. Choose server type:
   • Stdio: Local command-based servers
   • Remote: HTTP/SSE-based servers

Stdio Servers

{
  "name": "my-server",
  "command": "npx",
  "args": ["-y", "@mcp/server-name"],
  "env": {
    "API_KEY": "your-key"
  }
}

Remote Servers

{
  "name": "my-remote-server",
  "url": "https://mcp.example.com/sse"
}

Using MCP Tools

MCP tools appear in the tool selector with the format:

serverName__toolName

For example, github__create_issue from the GitHub MCP server.

Declaring Output Safety For Alma

Alma can compact large MCP tool outputs before they go back into model context. If your MCP server exposes a tool whose output must remain exact, you can declare that explicitly.

Supported values:

• exact: keep the tool result unchanged
• compact: allow Alma to shrink large text fields
• passthrough: skip compaction entirely, useful for binary-heavy payloads

Preferred approach: set _meta["alma/outputSafetyMode"] on the MCP tool:

{
  "name": "read_repo_file",
  "description": "Read repository file contents exactly",
  "_meta": {
    "alma/outputSafetyMode": "exact"
  }
}

Fallback approach: add a directive in the tool description:

{
  "name": "read_repo_file",
  "description": "Read repository file contents exactly [alma-output-safety: exact]"
}

Use exact for canonical source text, IDs, or structured data consumed programmatically. Use compact only for lossy-safe outputs such as logs, search results, and scraped page text.

Enabling MCP Tools

1. Click the Tools icon in the message input
2. Select All or Manual
3. Enable specific MCP tools as needed

OAuth Support

Some MCP servers require OAuth authentication:

1. Install the MCP server
2. Click Authorize when prompted
3. Complete the OAuth flow in your browser
4. The server is now authenticated

Managing OAuth

• View authorization status in server settings
• Revoke access by clicking Disconnect
• Re-authorize if token expires

Server Management

Server Status

View the status of connected servers:

• 🟢 Connected
• 🟡 Connecting
• 🔴 Disconnected/Error

Reconnecting

If a server disconnects:

1. Go to server settings
2. Click Reconnect

Removing Servers

1. Go to server settings
2. Click Delete
3. Confirm removal

Creating Custom Servers

You can create your own MCP servers using:

• Python with mcp package
• Node.js with @modelcontextprotocol/sdk

See the MCP Documentation for details.

Troubleshooting

"Server Failed to Start"

• Check server command and arguments
• Verify dependencies are installed
• Look at server logs

"Tool Not Available"

• Ensure server is connected
• Check if tool is enabled
• Verify OAuth if required

"Connection Lost"

• Server process may have crashed
• Check network connectivity
• Try reconnecting