---
title: Connect Agents
description: Connect Froglet to Claude Code, Codex, OpenClaw, and other MCP hosts.
---

<div class="learn-hero compact">
  <div>
    <div class="learn-pill">Agent setup</div>
    <p class="learn-lead">Connect agents to a real local or self-hosted Froglet node.</p>
    <p class="learn-sublead">The npm MCP package is local/actionable-first. Use `llms.txt` for the no-install hosted proof; use MCP when the agent needs provider/runtime access, token files, payment rails, or service publication.</p>
  </div>
</div>

## No-Clone Agent Bootstrap

For a user who wants a local Froglet node, start with the bootstrap:

```bash
curl -fsSL https://froglet.dev/agent | bash
```

The bootstrap installs the signed node, starts provider/runtime from published
images, and writes an MCP config backed by the published `froglet-mcp` image.
After that, the agent should use MCP actions for everything else.

Use Codex instead of Claude Code:

```bash
FROGLET_AGENT_TARGET=codex curl -fsSL https://froglet.dev/agent | bash
```

OpenClaw no-clone setup is not the default today because OpenClaw still loads a
repo-local plugin folder. Use the MCP path above for normal users and source
mode only for OpenClaw plugin development.

## MCP From npm

Use the published MCP package when the agent should operate an existing local
or self-hosted Froglet node:

```bash
npx froglet-mcp
```

That command starts an MCP stdio server. It defaults to `FROGLET_PROFILE=local`,
`FROGLET_PROVIDER_URL=http://127.0.0.1:8080`, and
`FROGLET_RUNTIME_URL=http://127.0.0.1:8081`. In that profile the agent should
call:

- `status` first, to verify provider/runtime reachability and report missing
  token files or local services plainly
- `plan_install` if the local node is missing and the target agent, footprint,
  role, payment rail, network, marketplace, or first use case is still
  ambiguous. If it returns `decision_required`, ask the user to pick a payment
  rail and recommend `none` for the first free demo
- `get_install_guide` only after the install profile is confirmed
- `plan_use_case` after local health is verified and before implementing the
  user's first consumer, provider, evidence, payments, batch, or GPU workflow
- service, settlement, marketplace, and publication actions only after the
  local node is reachable

The hosted proof is intentionally separate. It lives at
`https://froglet.dev/llms.txt` and covers only public free `demo.*` services.
Paid rails, persistent identity, custom service publication, long-running jobs,
batch, and GPU workloads are local/self-hosted concerns.

If you are packaging Froglet into an agent host rather than adding one MCP
server manually, use [Plugin Distribution](/learn/plugin-distribution/) for the
MCP Registry, Codex, Claude Code, OpenClaw, and NemoClaw order.

For MCP client config, use the package as the stdio command:

```json
{
  "mcpServers": {
    "froglet": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "froglet-mcp"],
      "env": {
        "FROGLET_PROFILE": "local",
        "FROGLET_PROVIDER_URL": "http://127.0.0.1:8080",
        "FROGLET_RUNTIME_URL": "http://127.0.0.1:8081",
        "FROGLET_PROVIDER_AUTH_TOKEN_PATH": "data/runtime/froglet-control.token",
        "FROGLET_RUNTIME_AUTH_TOKEN_PATH": "data/runtime/auth.token"
      }
    }
  }
}
```

For Codex-style TOML:

```toml
[mcp_servers.froglet]
command = "npx"
args = ["-y", "froglet-mcp"]
[mcp_servers.froglet.env]
FROGLET_PROFILE = "local"
FROGLET_PROVIDER_URL = "http://127.0.0.1:8080"
FROGLET_RUNTIME_URL = "http://127.0.0.1:8081"
FROGLET_PROVIDER_AUTH_TOKEN_PATH = "data/runtime/froglet-control.token"
FROGLET_RUNTIME_AUTH_TOKEN_PATH = "data/runtime/auth.token"
```

## Local config from the repo

These helper commands are repo-local and are kept for contributors. The normal
user path is `/agent`, not a clone. Clone only when you are developing Froglet,
testing the OpenClaw plugin, or editing checked-in examples:

```bash
git clone https://github.com/armanas/froglet.git
```

## Generate a config

```bash
cd froglet && ./scripts/setup-agent.sh --target claude-code
cd froglet && ./scripts/setup-agent.sh --target codex
cd froglet && ./scripts/setup-agent.sh --target openclaw
```

Optional override:

```bash
cd froglet && ./scripts/setup-agent.sh --target codex --out /tmp/froglet-codex.toml
```

## Default outputs

| Target | Default output | What it configures |
|-------|----------------|--------------------|
| `claude-code` | `.mcp.json` | Project-local MCP server for Claude Code |
| `codex` | `.codex/config.toml` | Project-local MCP server for Codex |
| `openclaw` | `.froglet/openclaw.config.json` | OpenClaw plugin config with the checked-in Froglet plugin |

## Default values

The helper writes local-profile values unless you override them with
environment variables:

- `FROGLET_PROFILE=local`
- `FROGLET_PROVIDER_URL=http://127.0.0.1:8080`
- `FROGLET_RUNTIME_URL=http://127.0.0.1:8081`
- `FROGLET_PROVIDER_AUTH_TOKEN_PATH=<repo-root>/data/runtime/froglet-control.token`
- `FROGLET_RUNTIME_AUTH_TOKEN_PATH=<repo-root>/data/runtime/auth.token`

When you run the local stack with Docker Compose, start it with
`FROGLET_HOST_READABLE_CONTROL_TOKEN=true` so the provider token path above is
actually readable from the host. The direct `froglet-node` path does not need
that opt-in.

## Activation

- **Claude Code**: restart Claude Code in the repo so it reloads `.mcp.json`.
- **Codex**: start Codex from the repo so it picks up `.codex/config.toml`.
- **OpenClaw**: use the generated config file directly and verify it with:

```bash
node integrations/openclaw/froglet/scripts/doctor.mjs \
  --config .froglet/openclaw.config.json \
  --target openclaw
```

## Checked-in MCP examples

The repo also ships checked-in MCP examples for:

- Claude Desktop
- Cursor
- Codex
- Docker-backed MCP

Those live under `integrations/mcp/froglet/examples/` and are covered by test.

## Local npm profile

If you prefer the published package but already have a local Froglet node,
point the MCP server at local provider/runtime URLs and token files:

```bash
FROGLET_PROFILE=local \
FROGLET_PROVIDER_URL=http://127.0.0.1:8080 \
FROGLET_RUNTIME_URL=http://127.0.0.1:8081 \
FROGLET_PROVIDER_AUTH_TOKEN_PATH=/absolute/path/to/froglet/data/runtime/froglet-control.token \
FROGLET_RUNTIME_AUTH_TOKEN_PATH=/absolute/path/to/froglet/data/runtime/auth.token \
  npx froglet-mcp
```

## Marketplace Registration

Use MCP wrappers instead of ad hoc HTTP when an agent is setting up discovery:

- `marketplace_register` for public HTTPS or Tor registration
- `marketplace_domain_claim` and `marketplace_domain_complete` for
  `*.providers.froglet.dev`

Tor registration is allowed only through `registration_transport=tor` and a
provider-advertised `http://<v3>.onion` origin. General `provider_url`
overrides still reject onion URLs so an LLM cannot silently route normal
invocations through arbitrary Tor endpoints.

## Next step

After the agent config exists, move to [Payment Rails](/learn/payment-rails/).