DocsWorking with Alran
MCP servers
Connect your own tools and services over the Model Context Protocol, per project.
How do I add an MCP server?
Create .mcp.json in the folder you start Alran from:
{
"mcpServers": {
"research": {
"type": "http",
"url": "https://example.com/mcp",
"headers": { "Authorization": "Bearer ${RESEARCH_MCP_API_KEY}" }
}
}
}${RESEARCH_MCP_API_KEY} is read from the environment of the shell that starts Alran, so the key stays out of the file:
read -r -s -p 'Research MCP API key: ' RESEARCH_MCP_API_KEY
export RESEARCH_MCP_API_KEY
alranOnly the main workspace folder is checked for .mcp.json, not its parents.
Check it
/mcp lists the servers and their state (configured, available or error); /mcp research filters. Ask Alran to use one of the server's tools with a small input and inspect the call with Ctrl+O. After you edit .mcp.json, run /mcp reload.
A connected server sees the workspace root and the arguments of every tool call. Connect services you trust.
From a plugin
Plugins can bring MCP servers too, in the Alran, Claude Code and Codex formats. See Plugins.
Common questions
How do I add an MCP server to a project?
Create a .mcp.json file in the folder you start Alran from and list the server under mcpServers with its type, url and headers. Keep secrets in environment variables and reference them in the headers, so the key stays out of the file. Only the main workspace folder is checked, not its parents.
How do I check that my MCP server is connected?
The command /mcp lists the servers and their state, configured, available or error, and /mcp research filters the list by name. After you edit .mcp.json, run /mcp reload.
What does a connected MCP server see?
A connected server sees the workspace root and the arguments of every tool call, so connect only services you trust. Plugins can bring MCP servers as well, in the Alran, Claude Code and Codex formats.