diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..48390eb
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,137 @@
+# AGENTS.md  
+Guide for autonomous coding agents (e.g., OpenAI Codex) working in **streamnative-mcp-server**
+
+---
+
+## 1 | Project snapshot
+* **What it is** – A fast, developer-friendly **Model Context Protocol (MCP) server** that lets LLM agents talk to **Apache Kafka, Apache Pulsar, and StreamNative Cloud** through a single, consistent interface.  
+* **Key outputs** – A single Go binary named **`snmcp`** (and a Docker image) that can run as a *stdio* or *SSE* server.  
+* **Primary language / tooling** – Go 1.22+, `make`, `golangci-lint`, `goreleaser`.
+
+---
+
+## 2 | Repo map (orient yourself quickly)
+
+| Path | What lives here | Touch with care? |
+|------|-----------------|------------------|
+| `cmd/streamnative-mcp-server/` | `main.go` entry‑point for the CLI/server | **yes** |
+| `pkg/` | Core library packages (Kafka tools, Pulsar tools, cloud integration, feature gating) | yes |
+| `sdk/` | Thin Go client helpers (generated) | can be re‑generated |
+| `docs/tools/` | One Markdown file per MCP tool – these are surfaced to the LLM at runtime | **yes** |
+| `.github/workflows/` | CI (lint, unit test, release) | only if changing CI |
+| `Makefile` | Local build helpers (`make build`, `make fix-license`, …) | safe |
+
+---
+
+## 3 | Required dev workflow
+
+> **Agents MUST follow every step below before committing code or opening a PR.**
+
+1. **Install deps**  
+   ```bash
+   brew install golangci-lint            # or use the install script
+   go install github.com/elastic/go-licenser@latest
+   ```
+
+2. **Build & unit tests**  
+   ```bash
+   make build            # invokes `go build …` with version metadata
+   go test ./...         # _there are few tests today – add more!_
+   ```
+
+3. **Static analysis & formatting**  
+   Run `golangci-lint run` and ensure **zero** issues. Linters enabled include `govet`, `staticcheck`, `revive`, `gosec`, etc.  
+   Follow `go fmt` / `goimports` import grouping.
+
+4. **License headers**  
+   ```bash
+   make fix-license      # injects Apache 2.0 headers via go-licenser
+   ```
+
+5. **Generate artifacts** (only if you edited code‑gen files)  
+   ```bash
+   go generate ./...
+   go mod tidy
+   ```
+
+6. **Commit & conventional message**  
+   Use **Conventional Commits** (`feat:`, `fix:`, `docs:` …). Keep title ≤ 72 chars and add a body explaining _why_.
+
+7. **Run the full release checks locally (optional but recommended)**  
+   ```bash
+   goreleaser release --snapshot --clean  # mirrors CI pipeline
+   ```
+
+---
+
+## 4 | How to run the server locally
+
+```bash
+# StreamNative Cloud (stdio)
+bin/snmcp stdio --organization $ORG --key-file my_sa.json
+# External Kafka
+bin/snmcp stdio --use-external-kafka --kafka-bootstrap-servers localhost:9092
+# External Pulsar
+bin/snmcp stdio --use-external-pulsar --pulsar-web-service-url http://localhost:8080
+```
+
+For HTTP/SSE mode add `sse --http-addr :9090 --http-path /mcp`.
+
+---
+
+## 5 | Coding conventions
+
+* **Package layout** – one feature per package; avoid cyclic imports.  
+* **Error handling** – wrap with `fmt.Errorf("context: %w", err)`; export sentinel errors where appropriate.  
+* **Logging** – rely on `zap` (already imported) with structured fields.  
+* **Tests** – use Go’s `testing` plus `testify/require`. When adding a tool, write at least:
+  * happy‑path invocation
+  * typical error path
+  * integration stub (may be skipped with `-short`)
+
+---
+
+## 6 | Common tasks for agents
+
+| Task | Checklist |
+|------|-----------|
+| **Add a new MCP tool** | 1) create package in `pkg/tools/...` 2) update `docs/tools/<tool>.md` 3) add to feature flag map 4) go‑vet + tests |
+| **Bug fix** | reproduce with unit test first → fix → ensure lint/test pass |
+| **Docs** | update both README **and** the per‑tool doc; regenerate table of contents |
+| **Release prep** | bump version tag, update changelog, run `goreleaser release --snapshot` |
+
+---
+
+## 7 | Programmatic checks the agent MUST run
+
+```bash
+go vet ./...
+golangci-lint run
+go test ./...
+make build                    # binary must compile for darwin/amd64 & linux/amd64
+```
+
+Codex **must not** finish a task until all checks pass locally. If CI fails, iterate until green.
+
+---
+
+## 8 | Pull‑request etiquette
+
+* Open PR against `main`, no new branches needed.  
+* Include a **Summary**, **Testing plan**, and **Docs updated** checklist.  
+* Mention which `--features` flags were affected, so reviewers know what to smoke‑test.  
+* If the change affects the public CLI, update `README.md` usage examples.
+
+---
+
+## 9 | AGENTS.md spec compliance
+
+This file follows the AGENTS.md spec described in the Codex system message (scope, precedence, required programmatic checks, etc.).  
+
+* Its scope is the **entire repository**.  
+* Deeper‑level AGENTS.md (not currently present) may override these instructions for their subtree.  
+* Direct human instructions in a prompt override anything here.
+
+---
+
+Happy hacking! 🚀