# Custom MCPs

import Screenshot from "@docs/Screenshot.astro"
import SurfaceTabs from "@docs/SurfaceTabs.astro"
import AskRen from "@docs/AskRen.astro"

A custom MCP connects Ren to a service outside the [Marketplace](/docs/concepts/apps/). MCP is a protocol that gives agents access to tools. For example, an internal documentation server can provide search tools to projects that use it.

Use an app when one exists, since apps include skills and a tested setup. Otherwise, connect a remote MCP server or run a local server on the space's machine.

The API resource is `mcp`. CLI commands use `ren mcps`.

## Add a custom MCP

A custom MCP is one of two kinds:

- **Remote:** a server reached over HTTP or SSE at a URL, like `https://mcp.example.com`.
- **Local:** a command that runs on the space's machine, like `npx -y @modelcontextprotocol/server-github`.

For a remote server, choose how it authenticates:

| Authentication                     | What you connect                                         |
| ---------------------------------- | -------------------------------------------------------- |
| None (no credential)               | Nothing. Use this for public servers.                    |
| OAuth                              | A signed-in account, through the provider's sign-in page |
| API key (bearer)                   | A token Ren sends in a header                            |
| Basic                              | A username and password                                  |
| Custom headers or query parameters | Values Ren places in the headers or URL you define       |

<SurfaceTabs>
<Fragment slot="app">

1. Open **Marketplace → Custom MCPs** and select **Add custom MCP**.
2. Choose where to add it: your organization, or a project. Choosing a project also adds the custom MCP to it.
3. Pick a **Transport**: **Remote** or **Local**.
4. For **Remote**, enter the **Server URL**. Choose an **Authentication** type. For **Local**, enter the **Command**. Add any required **Arguments** and **Environment variables**.
5. Enter a **Name**, then select **Add MCP**.

If the URL is already registered, Ren shows an error with **Add second account**. Select it only when you mean to reach the same server with a different account.

<Screenshot
  shot="custom-mcps/add"
  alt="The New custom MCP form with Transport set to Remote, a server URL, and the Authentication menu open"
/>

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Add our docs MCP server at https://mcp.acme.dev as a custom MCP and add it to this project. It uses OAuth." />

</Fragment>
<Fragment slot="cli">

```sh
ren mcps create --name "Acme docs" --type remote --mcp-server-url https://mcp.acme.dev --auth oauth
```

Run `ren mcps create --help` for local commands and other authentication types.

</Fragment>
</SurfaceTabs>

## Connect its credentials

If the server needs a credential, connect it before Ren uses the server. Ren saves it in the project's space, like an app connection. See [Credentials](/docs/concepts/credentials/).

<SurfaceTabs>
<Fragment slot="app">

1. Add the custom MCP to a project, or ask Ren to use it in a chat.
2. When Ren asks, select **Connect** and sign in, or enter the key, password, or fields the server needs.
3. Select **Continue**. The connection shows as connected.

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Connect the Acme docs MCP." />

Finish signing in or enter the key on the card Ren shows.

</Fragment>
<Fragment slot="cli">

For OAuth:

```sh
ren credentials connect <mcp> --vault-id <vault-id>
```

For a token, pipe it to `ren credentials create <vault-id> --auth-type bearer --mcp-id <mcp-id> --token-stdin`.

</Fragment>
</SurfaceTabs>

## Add it to a project

<SurfaceTabs>
<Fragment slot="app">

1. Open **Marketplace → Custom MCPs** and select the custom MCP.
2. Select **Add**, choose a project, and select **Add**.

The drawer lists the server's tools and the credentials it needs.

<Screenshot
  shot="custom-mcps/add-to-project"
  frame="detail"
  alt="The Add dialog for a custom MCP with the Storefront project chosen"
/>

</Fragment>
<Fragment slot="ask-ren">

<AskRen prompt="Add the Acme docs custom MCP to the Support project." />

</Fragment>
<Fragment slot="cli">

```sh
ren projects mcps add <project-id> --mcp-id <mcp-id>
```

</Fragment>
</SurfaceTabs>

To detach a custom MCP, select its trash icon in the composer's **Connect** menu. You can also run `ren projects mcps remove` or ask Ren. Detaching it doesn't delete its definition.

## Who can see a custom MCP

A custom MCP added at the organization level is visible to every member. One added to a project in your personal space is private to you. A credential is never part of a custom MCP's definition, so sharing the definition doesn't share your account.

Publish with `ren mcps publish <mcp-id>` or `mcp_publish`. Everyone can see the published definition, without authentication settings or credentials. Publishing is permanent, but you can deprecate it with `ren mcps deprecate`.