---
layout: home
title: '1MCP Agent - Unified MCP Runtime and CLI Mode for Agents'
description: 'Run one aggregated MCP runtime with 1MCP and give Codex, Claude, and other agents a thinner CLI workflow on top.'
head:
  - [
      'meta',
      {
        name: 'keywords',
        content: '1MCP,MCP runtime,CLI mode,agent workflow,Codex,Claude,template servers,async loading,lazy loading',
      },
    ]
  - ['meta', { property: 'og:title', content: '1MCP Agent - Unified MCP Runtime' }]
  - [
      'meta',
      {
        property: 'og:description',
        content: 'Aggregate many MCP servers behind 1mcp serve and use CLI mode for progressive discovery in agent sessions.',
      },
    ]
  - ['meta', { name: 'twitter:title', content: '1MCP Agent - Unified MCP Runtime' }]
  - [
      'meta',
      {
        name: 'twitter:description',
        content: 'Unified MCP runtime plus agent-friendly CLI mode for Codex, Claude, and direct MCP clients.',
      },
    ]

hero:
  name: '1MCP Agent'
  text: 'One runtime for MCP, one thinner workflow for agents'
  tagline: 'Run your MCP servers behind `1mcp serve`, then let agents use CLI mode for progressive discovery instead of carrying the full tool surface in context.'
  image:
    src: /images/logo.png
    alt: 1MCP Agent Logo
  actions:
    - theme: brand
      text: 5-Minute Setup
      link: /guide/quick-start
    - theme: alt
      text: CLI Mode
      link: /guide/integrations/cli-mode
    - theme: alt
      text: Architecture
      link: /reference/architecture

features:
  - icon: 🧭
    title: Progressive CLI Discovery
    details: 'Agents start with `instructions`, narrow with `inspect`, and only run the tool they actually need.'
  - icon: 🧩
    title: Unified Runtime
    details: '`1mcp serve` aggregates static and template-backed MCP servers behind one runtime.'
  - icon: 🪄
    title: Context-Aware Templates
    details: Template servers can be created per client or session instead of being fixed at startup.
  - icon: ⚡
    title: Async and Lazy Loading
    details: Start faster, load in the background, and expose less until a client or agent actually needs it.
  - icon: 📦
    title: Presets and Filters
    details: Reuse server sets across projects, clients, and compatibility bridges without duplicating config.
  - icon: 🔐
    title: Compatibility and Direct Paths
    details: 'Use `proxy` for maximum client compatibility with project context, or direct streamable HTTP when native HTTP transport is enough.'
---

## Why 1MCP?

1MCP solves two related problems at once:

- **Configuration sprawl**: too many clients each need their own MCP setup.
- **Agent context sprawl**: too many tools and schemas get injected into long-running agent loops.

The current product model is:

- `1mcp serve` is the unified runtime.
- CLI mode is the preferred agent-facing workflow on the unified runtime.
- `proxy` is the preferred non-CLI path because it keeps project context and works with the widest set of AI clients.
- Direct streamable HTTP remains supported for MCP-native clients that do not need project context.

Use this page to choose a path. If you already know you want a working setup, go straight to [Quick Start](/guide/quick-start).

## Start Here if You Use an AI Agent

This page is for Codex, Claude, Cursor, and similar agent workflows. The default path is: add one real upstream server, start `1mcp serve`, run `cli-setup`, then verify `instructions -> inspect -> run`.

## Start With the Right Path

- Want the fastest first success for an agent workflow? Go to [Quick Start](/guide/quick-start).
- Want the mental model for `instructions`, `inspect`, and `run`? Go to [CLI Mode](/guide/integrations/cli-mode).
- Want the broadest non-CLI client compatibility with project context? Go to [proxy](/commands/proxy).
- Want to connect an MCP-native client directly to the runtime over streamable HTTP? Go to [serve](/commands/serve).
- Want runtime details, loading behavior, or templates? Go to [Architecture](/reference/architecture).

## 5-Minute Setup Preview

```bash
npm install -g @1mcp/agent
1mcp mcp add context7 -- npx -y @upstash/context7-mcp
1mcp serve
```

Connect your agent to CLI mode:

```bash
1mcp cli-setup --codex
# or
1mcp cli-setup --claude --scope repo --repo-root .
```

Verify the workflow:

```bash
1mcp instructions
1mcp inspect context7
1mcp inspect context7/query-docs
1mcp run context7/query-docs --args '{"libraryId":"/mongodb/docs","query":"aggregation pipeline"}'
```

This is only the preview path. For prerequisites, success checks, and troubleshooting, continue to the [Quick Start guide](/guide/quick-start).

## Why This Path

- **Smaller working surface for agents**: progressive discovery avoids dumping the whole tool catalog into context.
- **One runtime for many clients**: agents, stdio-compatible clients through `proxy`, and direct HTTP MCP clients can share the same backend inventory.
- **Current runtime behavior, not a static proxy model**: async loading, lazy loading, templates, instructions, and presets are part of the main system design.

## Choose Another Path

<div class="vp-feature-grid">
  <a href="/guide/quick-start" class="vp-feature-box">
    <h3>Agent Quick Start</h3>
    <p>Best for first-time agent users who want a working setup before reading architecture or operator details.</p>
  </a>

  <a href="/guide/integrations/cli-mode" class="vp-feature-box">
    <h3>CLI Mode for Agents</h3>
    <p>Best for Codex, Claude, and similar agent loops that benefit from progressive discovery.</p>
  </a>

  <a href="/commands/serve" class="vp-feature-box">
    <h3>Proxy Compatibility Path</h3>
    <p>Best non-CLI path when you want project context, `.1mcprc`, template servers, and the widest client compatibility.</p>
  </a>

  <a href="/commands/serve" class="vp-feature-box">
    <h3>Direct Runtime Usage</h3>
    <p>Best for MCP-native HTTP clients that can use streamable HTTP directly and do not need project context.</p>
  </a>
</div>

<style>
.vp-feature-grid {
  display: grid;
  grid-template-columns: repeat(auto-fit, minmax(250px, 1fr));
  gap: 1rem;
  margin-top: 2rem;
}

.vp-feature-box {
  padding: 1.5rem;
  border: 1px solid var(--vp-c-border);
  border-radius: 8px;
  text-decoration: none;
  transition: border-color 0.25s;
}

.vp-feature-box:hover {
  border-color: var(--vp-c-brand);
}

.vp-feature-box h3 {
  margin: 0 0 0.5rem 0;
  font-size: 1.1rem;
}

.vp-feature-box p {
  margin: 0;
  color: var(--vp-c-text-2);
  line-height: 1.4;
}
</style>
