Astrail

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.

• Why Astrail

• Use cases

• Quick start

• See it in action

• How it works

• Capabilities

• Run the dashboard

• Connect to an endpoint

• Documentation

• Repository layout

• Development

• Current boundaries

• Contribute

• Community and links

• License

Why Astrail

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.

Related MCP server: MCP Bridge

Use cases

Examples to build with your own APIs and credentials:

These are integration ideas, not bundled end-to-end automations. Start with a small contract and verify each tool before enabling writes.

Quick start

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

See it in action

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.

How it works

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.

Capabilities

See the architecture guide for the request flow and module boundaries.

Run the dashboard

cp .env.local.example .env.local
npm run dev

Open 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.

Connect to an endpoint

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 list

Use 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.

Documentation

Repository layout

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

Development

npm test             # unit regressions and core smoke checks
npm run check        # repository checks, lint, types, tests, and build

CI also runs runtime security, OAuth, integration, export, and UI smoke checks. Changes to those areas require their corresponding tests; see CONTRIBUTING.md.

Current boundaries

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.

Contribute

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.

• Report a bug

• Propose an improvement

• Browse technical documentation

Community and links

Built by Riza and Aditya. Follow us for Astrail updates and what we’re building next.

Riza

Aditya

License

MIT. Dependencies retain their own licenses. Astrail names and logos are not covered by a trademark grant.

Why we open-sourced it

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