--- title: "AgentTwin developer resources" description: "Integrate AgentTwin agent testing through scoped OAuth, typed REST operations, the Node CLI and public documentation MCP." canonical: "https://agenttwin.si/developers/" --- # AgentTwin developer resources Use AgentTwin to test a prepared Node workflow against synthetic data and explicit assertions, or to investigate an unsafe retry under a supported fault. Do not assume discovery automatically creates a runnable world or that every detected provider has complete behavior coverage. ## Start with the CLI Install Node.js 22.12 or newer, then run `npx agenttwin init` inside your repository. Interactive init discovers local context, connects your account once, syncs metadata and returns. To try the executable reference first, follow the [clean and faulted example](/docs/quickstart/). Review all application files before execution. Local runs have host filesystem and network access. ## Local MCP for coding agents Run `npx agenttwin mcp` as an MCP stdio process in a coding agent that supports local MCP servers. The CLI exposes world, scenario, execution and inspection tools. This is a local stdio server, not a hosted Streamable HTTP endpoint. The team's private shared-memory service is not a public AgentTwin product API. ## REST API The API base is `https://api.agenttwin.si`. [OpenAPI](/openapi.json) documents the public health check, configured sign-in options and authenticated project listing. This is a documented subset of the gateway, not its complete internal interface. Customer resources require an account token or browser session. The [authentication guide](/auth/) explains CLI pairing and credential boundaries. Project-bound OAuth client credentials are supported with explicit per-operation scopes, one-hour access tokens and revocation. Start at [authentication](/auth.md) and its live discovery chain. ## Contracts and package access Read [supported provider operations](/docs/provider-operations/), [safety](/docs/safety/) and [current status](/docs/status/). Find the [npm package](https://www.npmjs.com/package/agenttwin), [CLI reference](/docs/cli/), [machine-readable index](/llms.txt) and [API catalog](/.well-known/api-catalog). Implementation source is currently private; repository access is not included with account sign-up. No official Python SDK is claimed. ## Public documentation MCP and skills The [official AgentTwin agent tools repository](https://github.com/Sashank-Singh/agenttwin-agent-tools) publishes `AGENTS.md`, opt-in Cursor rules, `plugin.json`, MCP configuration and two maintained skills. Review the files, then install with `npx skills add Sashank-Singh/agenttwin-agent-tools`. The official skills have public skills.sh pages: [agenttwin-prepare](https://www.skills.sh/sashank-singh/agenttwin-agent-tools/agenttwin-prepare) and [agenttwin-investigate](https://www.skills.sh/sashank-singh/agenttwin-agent-tools/agenttwin-investigate). Directory rankings and security assessments are maintained independently; publication is not an endorsement or a quality score. Connect a Streamable HTTP client to `https://agenttwin.si/mcp/docs` without credentials. It provides `search_docs` and `read_doc`, plus public documentation resources. This endpoint cannot access accounts, private repositories or run workflows. It supports MCP protocol versions 2025-03-26, 2025-06-18 and 2025-11-25 with JSON responses; standalone SSE is not offered. The per-instance aggregate limit is 600 requests per minute, with RateLimit-Policy, RateLimit and Retry-After on 429. Read the [server card](/mcp/docs/server-card). The public documentation server is [listed in the official MCP Registry](https://registry.modelcontextprotocol.io/?q=io.github.Sashank-Singh%2Fagenttwin-docs) as `io.github.Sashank-Singh/agenttwin-docs`. The [versioned registry record](https://registry.modelcontextprotocol.io/v0.1/servers/io.github.Sashank-Singh%2Fagenttwin-docs/versions/1.0.0) links back to this developer page and the public endpoint. Download the [AgentTwin skills plugin](/agenttwin-plugin.zip), review it, then use your agent client's supported local plugin or skill installer. Its [manifest](/agent-plugin/plugin.json) and [skill index](/.well-known/agent-skills/index.json) are public. The package contains workflow preparation and failure investigation skills, plus configuration for the public read-only documentation MCP. It does not install the CLI or execute commands automatically. Review each skill and your client permissions before installing. The [ARD catalog](/.well-known/ard.json) links these resources without exposing the private implementation repository. Browser clients that implement WebMCP receive public `search_agenttwin_docs` and `read_agenttwin_doc` tools. They search the same published corpus. Unsupported browsers keep their normal website behavior. ## OAuth 2.0 discovery AgentTwin implements OAuth 2.0 client credentials for trusted server-side clients. Fetch [authorization-server metadata](https://api.agenttwin.si/.well-known/oauth-authorization-server) and [protected-resource metadata](https://api.agenttwin.si/.well-known/oauth-protected-resource), then use the advertised [token endpoint](https://api.agenttwin.si/oauth/token) with privately stored credentials. The owner creates a project-scoped client through authenticated `POST /v1/oauth/clients`; no sales approval is required. See the [authentication walkthrough](/auth/) and [OpenAPI request schemas](/openapi.json). This OAuth authorization server does not implement OpenID Connect and intentionally does not publish `/.well-known/openid-configuration`. Its client-credentials flow is not WorkOS `agent_auth` identity registration: ID-JAG, anonymous registration and claim ceremonies are not supported. Read the real RFC 8414 metadata rather than inferring capabilities from an OpenID Connect probe. ## API versions and errors The published gateway subset uses `/v1`. Error bodies have an `error` string and may include a `message`; the error string may be an identifier or human-readable text. Preserve unknown errors. See `ErrorResponse` in OpenAPI. A 401 includes a protected-resource metadata hint. Use the explicit OAuth grant required by the operation, or an owner account token/browser session. [API lifecycle policy](/api-policy/) explains versioning and deprecation notices. There is no scheduled v1 retirement. The documented API now includes scoped OAuth, discovery reads, saved test drafts, asynchronous reviewed cloud-test submission and cursor-paginated run listing. `POST /v1/runs` accepts `Idempotency-Key` for retry safety; an accepted job returns HTTP 202 and `Location` to poll. A 202 is not a passed test. A configured E2B runner is required for actual cloud execution. Bulk operations are not implemented. Gateway responses expose an enforced per-instance aggregate budget of 1200 requests/minute through Structured Fields `RateLimit-Policy` and `RateLimit` headers, with `Retry-After` seconds on 429. OAuth exchange additionally has a per-peer 120/minute budget; peers behind the same trusted proxy share it. These are process-local quotas, not a distributed per-customer SLA. Documentation MCP has its separate 600/minute aggregate limit. The headers follow the current IETF RateLimit Structured Fields convention; this convention is still a draft, not a final RFC. [Try the credential-free synthetic sandbox](/sandbox/) before connecting customer resources. No sales form or cloud credentials are needed for the shipped local reference example. ## Machine-readable documents Published guide Markdown includes YAML metadata followed by the visible page content, except /auth.md which begins directly with its top-level heading for authentication discovery. HTML clients can discover the same representation using alternate links or `Accept: text/markdown`. Source-bound review dates appear in the sitemap; builds do not manufacture update times. ## NLWeb documentation search `POST https://agenttwin.si/ask` provides NLWeb v0.55 list-mode retrieval over the same public documentation as the docs MCP. No account is needed. Send JSON `{"query":{"text":"timeout"},"prefer":{"mode":"list","streaming":false}}`. Answers include `_meta.response_type`, `_meta.version` and typed `results` with source URLs. Set `prefer.streaming` to `true` for finite Server-Sent Events: `start`, indexed `result` items, optional `error`, then `complete`. It does not generate summaries, execute actions or access accounts; unsupported modes/formats return typed failures. No conversation state is retained. The 16 KiB request limit, 200-character query limit and shared 600-requests/minute public documentation quota apply. Requests above quota return 429 with `Retry-After`; other failures carry an NLWeb `error.code`. `NO_RESULTS` is an HTTP 200 failure response, not an invented answer. The [OpenAPI definition](/openapi.json) declares this operation on the website origin.