MCPs

An MCP (Model Context Protocol server) is Ren’s primitive for giving an agent access to external tools and services. Where a skill teaches an agent how to do something, an MCP gives it something to reach out to: an API, a database, a search engine, or any service that speaks the MCP protocol.

Remote vs. local

MCPs come in two flavors, depending on where the server runs:

Remote MCPs are hosted somewhere on the internet: your infrastructure, a vendor’s API, or a shared service. You give Ren a URL, and the agent connects to it at runtime. This is the common case for third-party services (Slack, GitHub, databases) and for any server you already host.

Local MCPs run inside Ren’s sandbox. Instead of a URL, you provide a command (for example, npx @example/mcp) and Ren spins up the process on demand. Local MCPs are useful for tools that don’t have a hosted version, or when you want the server to run in the same environment as the agent.

The choice between remote and local is mostly about where the server lives. The agent doesn’t care. It calls tools the same way regardless.

Transport protocols

When an agent connects to an MCP server, it uses one of three transports:

Streamable HTTP (default): the modern MCP transport. A single HTTP endpoint that supports both request-response and streaming. Use this unless you have a reason not to.
SSE: server-sent events over HTTP. The original MCP transport, still supported for backward compatibility with older servers.
Stdio: standard input/output, used exclusively by local MCPs. Ren pipes messages to and from the spawned process.

For remote MCPs, streamable HTTP is the sensible default. For local MCPs, stdio is the only option and is chosen automatically.

Authentication

An MCP server may require authentication before the agent can use it. Ren supports four auth types:

None (default): no credentials needed. The server is open or uses IP-based allowlisting.
API key: a static key sent as a header or query parameter. You configure which header or parameter name the server expects, including the Authorization header for bearer-style tokens. Simple and common for SaaS APIs.
Basic: HTTP Basic authentication (username and password), for services that still require it.
OAuth: the full OAuth 2.0 flow. You configure scopes, token endpoints, and authorization endpoints. Ren handles the redirect and token exchange at runtime. Used for services that require user-delegated access (e.g., “act on behalf of this Slack user”).

Credentials and vaults

Credentials are not stored on the MCP definition. Instead, an MCP declares the credential slots it needs (a name, description, and auth type). At runtime, Ren fills those slots from a vault that holds the actual secret values.

This separation means secrets never appear in a definition that may be shared or published, and the same MCP can serve different agents with different credentials: a shared “Slack” MCP can use one team’s token in project A and another’s in project B.

How MCPs attach to agents

MCPs are attached to an agent version, so each version can have a different set of tools. You might add a new server in v2 without touching v1.

When an agent starts a session, Ren collects its MCPs, fills their credentials from the vault, and presents the available tools to the model. The agent decides which to call, just as it decides which skills to invoke.

Like agents and skills, MCPs have a scope:

Private: only visible to you.
Org: visible to everyone in your organization, for shared infrastructure like a company-wide database MCP.
Public: published to the registry for anyone to install.

Publishing an MCP shares it without revealing credentials. The credential slots travel with the definition, but the secrets stay in each installer’s vault.

MCPs vs. skills

MCPs and skills both extend what an agent can do, but they operate at different layers:

	MCP	Skill
What it provides	External tools and services	Instructions and scripts the agent runs locally
Where it runs	On a remote server or in a sandbox process	Inside the agent's reasoning loop
Protocol	MCP (tools/resources/prompts)	Ren skill protocol (instructions + optional scripts)
State	The server owns its own state	Stateless. Invoked once, returns a result
Auth	May require credentials (API key, OAuth, etc.)	No auth. It's part of the agent
Analogy	A phone line to an external service	A procedure the agent has memorized

MCP

What it provides: External tools and services
Where it runs: On a remote server or in a sandbox process
Protocol: MCP (tools/resources/prompts)
State: The server owns its own state
Auth: May require credentials (API key, OAuth, etc.)
Analogy: A phone line to an external service

Skill

What it provides: Instructions and scripts the agent runs locally
Where it runs: Inside the agent's reasoning loop
Protocol: Ren skill protocol (instructions + optional scripts)
State: Stateless. Invoked once, returns a result
Auth: No auth. It's part of the agent
Analogy: A procedure the agent has memorized

The practical distinction: if the capability lives outside Ren and the agent needs to call it over a network, it’s an MCP. If the capability is a set of instructions or a script the agent carries and runs itself, it’s a skill. Many agents use both: skills for reasoning patterns and local actions, MCPs for reaching external systems.

Discovering and creating MCPs

The Ren CLI provides commands for working with MCPs:

ren mcps create --name "X" --mcp-server-url "https://...": create a remote MCP.
ren mcps create --name "X" --type local --command "npx @example/mcp": create a local MCP.
ren mcps list: view the MCPs available to you.
ren mcps search: find published MCPs in the registry.

For the full walkthrough of registering an MCP and wiring it to an agent, see Connect an MCP server.