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 ^20.19.0 || ^22.12.0 || >=23.0.0 for npm installs
• 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 hooks that run bootstrap at startup, supplying runtime guidance and a private owner credential to the agent. For Codex, it also prints required changes for config.toml; it does not apply those changes. Copy the printed snippet into config.toml before starting Codex. See cli-setup for target and scope details.

5. Verify the workflow

Enable and trust the hooks, then open a new agent session. Verify that it receives runtime guidance and establishes ownership. With a named or implicitly discovered local runtime, supported Codex sessions resolve their owner and assigned project automatically. Claude and hosts without automatic owner lookup add their own bootstrap --project-owner <own-file> to each call. Each worker uses its own startup context and credential. Ask the agent to follow this flow; you do not need to repeat these commands manually:

# Only if current target guidance is missing or needs refreshing.
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

• Startup delivers the CLI playbook and this session’s owner credential; instructions is only needed to fetch missing or refreshed guidance
• 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
• For Codex, the printed config.toml changes are present before the next Codex session starts

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

For a workflow across repositories and Git worktrees, see Working Across Projects and Worktrees.

• 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 satisfies ^20.19.0 || ^22.12.0 || >=23.0.0: 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