Turn APIs into agent tools. Control every call.
Open-source API-to-MCP generation and runtime.
Typed tools, credential handling, approval policies, and execution traces in one codebase.
Website · Quick start · Demo · How it works · Docs · Contribute
Astrail turns API definitions into typed tools that agents can discover and call through the Model Context Protocol (MCP). Import a spec, generate the tools, and configure how they execute. The runtime brings authentication, OAuth, approvals, network policy, and traces into the same workflow.
- Start with the API you already have. Import OpenAPI/Swagger, Google Discovery, GraphQL, or an existing HTTP MCP server.
- Make execution explicit. Configure allow, approval, and block policies alongside credential and scope checks.
- Inspect the path from tool to endpoint. Calls follow deterministic endpoint maps; Code Mode compiles supported calls without evaluating generated JavaScript.
- Try the core locally. The offline example generates and validates tools without a database, account, model key, or upstream API call.
On this page
An agent needs more than an API description to take an action: it needs a tool schema, a route to execute, credentials, and rules for when the call is allowed. Astrail brings those pieces into one workflow.
Import the API definition, inspect the generated tools, then expose a configured MCP endpoint. Runtime calls resolve through endpoint maps, pass authentication and policy checks, and execute against the upstream API. Traces help you inspect what happened. Generated source is available for export; the hosted runtime does not evaluate it.
Examples to build with your own APIs and credentials:
| Workflow | Tools to expose | Policy to consider |
|---|---|---|
| Support | Find tickets and prepare updates | Require approval for changes |
| Operations | Look up inventory and create purchase orders | Allow reads; review purchases |
| Internal tools | Search CRM records and update account fields | Limit tools and credentials by role |
These are integration ideas, not bundled end-to-end automations. Start with a small contract and verify each tool before enabling writes.
Requires Node.js 22.18+ and npm. No database, model API key, or account is needed for this example.
git clone https://github.com/codewithriza/astrail.git
cd astrail
npm ci
npm run demo:offline
Visual summary of the runnable offline example below.
The example runs the real generation pipeline against a small Notes API spec:
notes_list_notes allow
notes_create_note approval
notes_delete_note block
It validates the generated tools and their policies, with network access disabled. It generates tools; it does not execute the fictional Notes API. Read the example, change the spec, and inspect the result.
Architecture overview. Future adapters are planned; website support is limited to public read workflows. See current boundaries for deployment and export limitations.
flowchart LR
A[API definition] --> B[Typed MCP tools]
B --> C{Execution policy}
C -->|Allow| D[HTTP endpoint]
C -->|Approval required| E[Approval check]
E --> D
C -->|Block| F[Request rejected]
The offline example stops at generation and policy validation. A configured deployment adds authentication, credential handling, execution, and traces.
| Area | Included |
|---|---|
| Import | OpenAPI/Swagger, Google Discovery, GraphQL, existing HTTP MCP servers |
| Generate | Typed tools, searchable endpoint catalogs, constrained Code Mode |
| Control | Authentication, OAuth scopes, approvals, network policy, bounded retries |
| Inspect | Execution traces and request validation |
| Connect | Dashboard, CLI, TypeScript and Python clients, SDK exports |
| Export | Manual Cloudflare Worker exports with a narrower runtime feature set |
See the architecture guide for the request flow and module boundaries.
cp .env.local.example .env.local
npm run devOpen localhost:3000. The local environment example enables development-only demo auth. This preview does not replace a persistent backend. For stored servers, real users, and provider credentials, configure Neon and authentication, apply the schema, and follow the platform setup guide.
AI-assisted generation is optional. Deterministic generation works without ANTHROPIC_API_KEY. Hosted operation currently depends on Neon Auth/Data API; this is not yet a database-independent, one-command deployment.
For container deployment, follow the Docker guide.
After creating a server in your own deployment:
export ASTRAIL_MCP_ENDPOINT='https://YOUR_HOST/api/mcp/YOUR_SERVER_ID'
export ASTRAIL_API_KEY='YOUR_API_KEY'
node bin/astrail.mjs status
node bin/astrail.mjs tools listUse node bin/astrail.mjs help for calls, connector discovery, and the stdio bridge. See the CLI guide for configuration and protocol limits. Public package releases are not yet available; run the CLI from this checkout.
| I want to… | Start here |
|---|---|
| Try generation without credentials | Offline example |
| Run a local demo | Demo walkthrough |
| Configure a persistent deployment | Platform setup · Docker |
| Connect an MCP client | CLI and stdio bridge |
| Understand the codebase | Architecture |
| Review execution and security controls | Runtime permissions · Threat model |
| Make a contribution | Contributing · Engineering standards |
| Explore all guides | Documentation index |
app/ Next.js pages and API routes
lib/ Generation, authentication, and runtime logic
components/ Shared UI components
bin/ CLI and transport helpers
sdk/ TypeScript and Python clients
database/ Base schema and incremental migrations
config/typescript/ Focused smoke-test compiler configurations
tests/ Unit, SDK, and browser tests
scripts/ Development and verification commands
examples/ Runnable examples
docs/ Setup and architecture guides
npm test # unit regressions and core smoke checks
npm run check # repository checks, lint, types, tests, and buildCI also runs runtime security, OAuth, integration, export, and UI smoke checks. Changes to those areas require their corresponding tests; see CONTRIBUTING.md.
Astrail is an early project. Website automation is limited to public read workflows. Code Mode statically compiles supported calls; it cannot execute arbitrary JavaScript. Worker export has a narrower feature set than the hosted runtime. Multi-region deployments need distributed limits and external edge protection. Provider OAuth applications and scopes require operator configuration.
Do not treat tool descriptions or approval metadata alone as an authorization boundary. Read the threat model, security policy, and runtime permissions before exposing a deployment.
Useful starting points are reproducible importer bugs, minimal OpenAPI fixtures, clearer setup instructions, and tests for provider edge cases. Start with the contribution guide and roadmap. Open a discussion before a large architectural change.
Built by Riza and Aditya. Follow us for Astrail updates and what we’re building next.
Riza
Aditya
MIT. Dependencies retain their own licenses. Astrail names and logos are not covered by a trademark grant.
We built Astrail because connecting agents to APIs meant writing the same tool definitions, auth handling, and request logic over and over. We wanted to make that easier.
We applied to YC twice. For S26, we got an interview with YC partners Harshitha Arora and Diana Hu. For F26, we made the top 10%. We decided we wanted to work on something else, so we open-sourced Astrail. There’s still plenty here to use and build on. Play around with it and let us know what you make.
— Riza & Aditya