Optimism Documentation

These docs are built to be read by AI assistants and agents, not just browsers. Every page is available as plain markdown, the whole site publishes a machine-readable index, and a hosted MCP server exposes search over the content. This page covers the three ways to put them to work: reading the docs as an agent, connecting the hosted MCP server, and starting from curated prompts.

Read the Docs as an Agent

The Documentation Index: llms.txt

The site publishes an llms.txt index at:

https://docs.optimism.io/llms.txt

It is a plain-markdown listing of the site’s pages with their URLs. Point an assistant at it to discover what exists before fetching individual pages. This is the recommended entry point for any agent working with these docs.

Per-Page Markdown

Every page is served as raw markdown at its own URL with .md appended. For example, the Node Operator Overview page is available as:

https://docs.optimism.io/node-operators/overview.md

Fetching the .md form skips the HTML shell, navigation, and scripts, so an assistant gets exactly the content of the page in a fraction of the tokens. Prefer it over the HTML URL whenever your tooling fetches pages programmatically. Every page in these docs has a contextual menu (next to the page title) with assistant-ready actions:

Copy page: copies the page as markdown, ready to paste into any chat.
Open in ChatGPT: opens a ChatGPT conversation preloaded with the page.
Open in Claude: opens a Claude conversation preloaded with the page.
Copy MCP server URL: copies the hosted MCP server address for your client configuration.

Use it when you are reading a page and want to hand it to an assistant without constructing URLs by hand.

Tips for Agents Reading These Docs

Start from llms.txt to map the site, then fetch only the .md pages you need.
These docs describe how to use the OP Stack. The normative protocol definition lives in the OP Stack specifications - when a docs page and the specs disagree, the specs win.
Configuration flags and versions change between releases. Confirm load-bearing values against the linked source or release notes before acting on them.

Connect the Hosted MCP Server

The Model Context Protocol (MCP) is an open standard for connecting AI assistants to external tools and data sources. These docs are hosted on Mintlify, which automatically generates and hosts an MCP server for the site. The server exposes a search tool over the documentation, so a connected assistant (Claude Code, Claude Desktop, Cursor, and others) can look up current OP Stack content instead of relying on stale training data.

Option 1: The Hosted MCP Server (Recommended)

The docs MCP server is available over HTTP at:

https://docs.optimism.io/mcp

Add the server to your client

For Claude Code, run:

claude mcp add --transport http optimism-docs https://docs.optimism.io/mcp

For Cursor, Claude Desktop, and other clients that use a JSON configuration, add the server URL:

{
  "mcpServers": {
    "optimism-docs": {
      "url": "https://docs.optimism.io/mcp"
    }
  }
}

You can also connect from any page of these docs: the contextual menu (next to the page title) includes an option to copy the MCP server details for your client.

Verify it works

Ask your assistant:

Using the optimism-docs MCP server, find the page about running a node
from source and summarize its hardware requirements.

A correctly wired assistant calls the server’s search tool, locates Building and Running an OP Stack Node From Source, and answers from the live page.

Option 2: Direct Fetching (No MCP Server Required)

If your assistant can fetch web pages but does not support MCP, no setup is needed. The site’s machine-readable surfaces - the llms.txt index and per-page markdown - work with any assistant that can fetch URLs. Give it the index and the URL convention:

The Optimism docs publish a machine-readable index at
https://docs.optimism.io/llms.txt. Any page is available as raw
markdown by appending .md to its URL. Use the index to find relevant
pages, then fetch their .md versions.

Add that to your assistant’s project instructions (for example CLAUDE.md, .cursorrules, or a system prompt) and it will resolve OP Stack questions against the live docs. If your tooling only reaches the network through MCP and cannot use the hosted server, the reference fetch server (uvx mcp-server-fetch) plus the instruction block above achieves the same result. If the hosted MCP endpoint is not responding, open an issue so we can investigate.

Prompt Starters

Copy-paste prompts for common OP Stack tasks, ready for any AI assistant that can fetch URLs. Each prompt names its intended persona, grounds the assistant in specific docs pages (fetched as per-page markdown), and tells it what to produce. Replace the bracketed placeholders with your own details before sending. If your assistant cannot fetch URLs, open the linked pages and use the contextual menu’s Copy page action to paste them in instead.

Audit My Batcher Configuration for Cost

Persona: chain operator Data availability is usually a chain’s largest onchain operating cost, and the batcher configuration controls it. Grounding pages: Configure the Batcher and Transaction Fees 101.

Read https://docs.optimism.io/chain-operators/guides/configuration/batcher.md
and https://docs.optimism.io/chain-operators/guides/management/transaction-fees-101.md

Here is my current op-batcher configuration: [paste your flags or env vars].
My chain posts roughly [N] transactions per day and targets [blobs / calldata].

Audit the configuration for data-availability cost: identify settings that
increase posting cost, explain the trade-off each one controls (cost vs.
latency vs. safety), and propose a revised configuration with reasoning.
Flag any flag you are not sure still exists so I can check it against
op-batcher --help for my release.

Walk Me Through the Deposit Flow

Persona: app developer Understand what actually happens between an L1 deposit call and the transaction appearing on L2 before you build on it. Grounding pages: Deposit Flow and Deposit Transactions.

Read https://docs.optimism.io/op-stack/bridging/deposit-flow.md and
https://docs.optimism.io/app-developers/tutorials/bridging/deposit-transactions.md

Walk me through the full lifecycle of a deposit from L1 to L2: which
contract I call, what events are emitted, how the L2 transaction is
derived, and what latency and failure modes to expect. Then show me the
minimal code to trigger a deposit from my app. I am building
[describe your app].

Plan a Fault-Proof Challenger Deployment

Persona: chain operator Every permissionless fault-proof chain needs an honest challenger watching its dispute games. Grounding pages: OP-Challenger Explainer and How to Configure Challenger for Your Chain.

Read https://docs.optimism.io/op-stack/fault-proofs/challenger.md and
https://docs.optimism.io/chain-operators/guides/configuration/op-challenger-config-guide.md

I operate an OP Stack chain with fault proofs enabled on [network].
Produce a deployment plan for op-challenger: the role it plays, the
resources and keys it needs, the bond funding it requires, the
configuration I must set, and the monitoring I should attach. List open
questions I need to answer about my own chain before deploying.

Bridge ETH From L1 in My App

Persona: app developer Move ETH between Ethereum and an OP Stack chain programmatically. Grounding page: Submitting Transactions From L1.

Read https://docs.optimism.io/app-developers/tutorials/bridging/cross-dom-bridge-eth.md

Using the approach in this tutorial, write the code for my app to bridge
ETH from [L1 network] to [L2 network] and report deposit status to the
user. My stack is [TypeScript framework / environment]. Point out where
testnet and mainnet configuration differ, and what the user experience
should show while the deposit is in flight.

Explain My Transaction’s Fee Breakdown

Persona: app developer OP Stack transactions pay an execution fee and a data-availability fee; estimating only one of them causes bugs. Grounding page: Transaction Fees on OP Mainnet.

Read https://docs.optimism.io/op-stack/transactions/fees.md

Explain every component of the fee my transaction pays on an OP Stack
chain, how each is calculated, and which ones fluctuate with L1 gas
prices. Then show me how to estimate the total fee for a transaction
correctly in my app, and the common estimation mistakes to avoid.
Here is my current estimation code: [paste code, optional].

Debug a Stuck Withdrawal

Persona: app developer Withdrawals are multi-step and time-delayed by design; most “stuck” withdrawals are actually mid-flight. Grounding pages: Withdrawal Flow and Transaction Finality.

Read https://docs.optimism.io/op-stack/bridging/withdrawal-flow.md and
https://docs.optimism.io/op-stack/transactions/transaction-finality.md

A withdrawal from [L2 network] appears stuck: [describe what you did,
when, and the transaction hash or current status]. Using the withdrawal
lifecycle in these docs, determine which stage the withdrawal is in,
whether the delay is expected protocol behavior or an actual problem,
and exactly what action (if any) unblocks the next step.

Contributing

The prompts above are curated: each one maps to a task readers actually arrive with, and each grounds the assistant in maintained docs pages. To propose a new prompt or fix a stale one, open an issue or edit this page.

Quickstart

Guides

Tutorials

Tools

Reference

Archive

Use the Docs with AI

Read the Docs as an Agent

The Documentation Index: llms.txt

Per-Page Markdown

The Contextual Menu

Tips for Agents Reading These Docs

Connect the Hosted MCP Server

Option 1: The Hosted MCP Server (Recommended)

Option 2: Direct Fetching (No MCP Server Required)

Prompt Starters

Audit My Batcher Configuration for Cost

Walk Me Through the Deposit Flow

Plan a Fault-Proof Challenger Deployment

Bridge ETH From L1 in My App

Explain My Transaction’s Fee Breakdown

Debug a Stuck Withdrawal

Contributing

​Read the Docs as an Agent

​The Documentation Index: llms.txt

​Per-Page Markdown

​The Contextual Menu

​Tips for Agents Reading These Docs

​Connect the Hosted MCP Server

​Option 1: The Hosted MCP Server (Recommended)

​Option 2: Direct Fetching (No MCP Server Required)

​Prompt Starters

​Audit My Batcher Configuration for Cost

​Walk Me Through the Deposit Flow

​Plan a Fault-Proof Challenger Deployment

​Bridge ETH From L1 in My App

​Explain My Transaction’s Fee Breakdown

​Debug a Stuck Withdrawal

​Contributing

Read the Docs as an Agent

The Documentation Index: llms.txt

Per-Page Markdown

The Contextual Menu

Tips for Agents Reading These Docs

Connect the Hosted MCP Server

Option 1: The Hosted MCP Server (Recommended)

Option 2: Direct Fetching (No MCP Server Required)

Prompt Starters

Audit My Batcher Configuration for Cost

Walk Me Through the Deposit Flow

Plan a Fault-Proof Challenger Deployment

Bridge ETH From L1 in My App

Explain My Transaction’s Fee Breakdown

Debug a Stuck Withdrawal

Contributing