Skip to content
Ren Docs
Book a demo

Create a custom MCP

Connect an MCP (Model Context Protocol) server to an agent so the agent can call external tools at runtime. MCP servers extend what an agent can do: from searching the web to querying databases to managing infrastructure.

Remote vs. local

MCP servers come in two types:

  • Remote: the server is hosted at a URL. Ren proxies requests to it. Requires mcpServerUrl.
  • Local: the server runs as a process on the agent’s sandbox. Requires command (and optional args). The sandbox starts the process and communicates over the chosen transport.

Transport options: streamable-http (default for remote), sse (server-sent events, for legacy remote servers), stdio (default for local).

Authentication

MCP servers declare their auth requirement when you create them. Ren resolves credentials from the agent’s vault at runtime. They are never stored inline on the MCP object.

Auth type When to use What Ren does
none Public or no-auth servers (default) No credential lookup
api_key Servers that expect an API key header or query param Reads the named credential from the vault and injects it
bearer Servers that expect a Bearer token Reads the named credential and sends it as a Bearer header
oauth Servers that require OAuth 2.0 Starts an OAuth flow, stores the token in the vault, refreshes automatically

For api_key and bearer, declare requiredCredentials on the MCP so Ren knows which vault entries to resolve. See Store and share files for vault setup.

In the UI

In the UI

  1. Open MCPs in the sidebar and click New MCP.

  2. Choose Remote (enter the server URL) or Local (enter the command and args), then pick the auth type.

  3. Open the agent you want to extend, select a version, and add the MCP under MCPs.

  4. Save. The next session on that agent version can call the MCP’s tools.

Create and attach programmatically

  1. Create a remote MCP server:

    Terminal window
    ren mcps create \
      --name "web-search" \
      --mcp-server-url "https://search.example.com/mcp" \
      --auth none

    Or create a local MCP server:

    Terminal window
    ren mcps create \
      --name "local-tools" \
      --type local \
      --command "npx" \
      --args '["-y","@example/mcp-server"]' \
      --transport stdio

    The response includes the MCP id (e.g. mcp_abc123).

  2. Attach the MCP to an agent version:

    Terminal window
    ren agents get agt_abc123 > /tmp/agent.json   # splice mcp_abc123 into mcpIds
    ren agents versions create agt_abc123 \
      --body @/tmp/agent.json \
      --release-notes "attach paid-api MCP"

    A version’s dependency lists are full-replace, so read the current agent first and send the complete list back.

For servers requiring an API key, declare the credential and store it in a vault:

Terminal window
ren mcps create \
  --name "paid-api" \
  --mcp-server-url "https://api.example.com/mcp" \
  --auth api_key \
  --required-credentials '[{"name":"EXAMPLE_API_KEY","description":"API key for Example"}]'

Then store the key in a vault and attach the vault to the agent’s pod.