---
title: "MCP servers · Alran Code Docs"
url: https://alran.dev/en/docs/mcp
locale: en
updated: 2026-11-16
---

[Docs](https://alran.dev/en/docs)Working with Alran

# MCP servers

Connect your own tools and services over the Model Context Protocol, per project.

On this page

[How do I add an MCP server?](#add) [Check it](#check) [From a plugin](#plugins) [Common questions](#faq)

## How do I add an MCP server? {#add}

Create `.mcp.json` in the folder you start Alran from:

```json
{
  "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:

```bash
read -r -s -p 'Research MCP API key: ' RESEARCH_MCP_API_KEY
export RESEARCH_MCP_API_KEY
alran
```

Only the main workspace folder is checked for `.mcp.json`, not its parents.

## Check it {#check}

`/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}

Plugins can bring MCP servers too, in the Alran, Claude Code and Codex formats. See [Plugins](https://alran.dev/en/docs/plugins#local).

## Common questions {#faq}

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.

[PreviousPlugins, skills and hooks](https://alran.dev/en/docs/plugins) [NextHeadless and CI](https://alran.dev/en/docs/headless)
