Quick Start

This page is for AI agent users first. Its job is narrow: get you to one working 1mcp serve runtime plus one verified CLI-mode workflow.

By the end of this guide, you will have:

• One real upstream MCP server added to 1MCP
• A running 1mcp serve instance
• Codex or Claude configured with cli-setup
• A verified instructions -> inspect -> run workflow

If you want proxy, direct streamable HTTP, or deeper runtime operator docs instead, jump to Choose another path.

Prerequisites

• Node.js 18+
• An AI agent client such as Codex or Claude

5-Minute Agent Setup

1. Install 1MCP

npm install -g @1mcp/agent

2. Add one real upstream MCP server

Use one recognizable upstream server so you can prove the workflow on something real immediately:

1mcp mcp add context7 -- npx -y @upstash/context7-mcp

3. Start the runtime

1mcp serve

Keep that shell running. Open a second shell for the next steps.

4. Connect your agent with cli-setup

Pick one client:

1mcp cli-setup --codex

1mcp cli-setup --claude --scope repo --repo-root .

The command installs the startup files that tell the agent to use instructions, inspect, and run in order. See cli-setup for target and scope details.

5. Verify the workflow

Run the same commands your agent will use:

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

Success looks like this

• instructions explains the CLI workflow and shows the available runtime context
• inspect context7 lists tools from the upstream server
• inspect context7/query-docs shows the tool schema before invocation
• run ... returns a real result from the upstream server

At that point your agent can use 1MCP through CLI mode without reading another setup page.

What this page does not cover

• Full runtime configuration
• Authentication and team deployment
• proxy and maximum-compatibility stdio flows
• Direct streamable HTTP MCP attachment details

Use the linked pages below once the first workflow works.

Why this is the recommended path

For agent sessions, CLI mode is the narrowest path to a working setup:

• 1mcp serve gives you one aggregated runtime behind the scenes
• cli-setup installs the bootstrap files for the agent
• instructions -> inspect -> run keeps the tool surface progressive instead of broad

Choose another path

stdio proxy

Use this if you want the broadest client compatibility after CLI mode.

proxy is usually the better fallback than direct streamable HTTP because it keeps project context through .1mcprc, supports template MCP servers, and is easier to standardize with one-time global setup.

• Proxy command

Direct MCP attachment

Use this if your client already speaks MCP natively over streamable HTTP and you do not need project context.

• Serve command
• Architecture

Runtime operators

Use these once the basic flow works and you want to manage the runtime itself:

• Configuration
• Authentication
• Presets

Next Steps

• CLI Mode guide for the conceptual model
• Add more servers to expand the runtime
• Enable authentication for shared or production setups

Common Issues

1mcp serve fails to start

• Check that Node.js 18+ is installed: node --version
• Re-run 1mcp mcp list to confirm the upstream server was added

cli-setup does not affect my agent

• Make sure you picked the correct target: --codex or --claude
• For repo-scoped setup, verify you ran the command from the intended repository root

inspect shows no tools

• Confirm 1mcp serve is still running in the first shell
• Run 1mcp instructions again to confirm the current runtime state

run fails against the upstream server

• Re-run 1mcp inspect context7/query-docs and check the required arguments
• Check the serve output for upstream startup errors