Astrail docs
Quickstart
Build your first hosted MCP endpoint and owned SDK bundle from a real API contract. You'll discover an OpenAPI spec, generate MCP tools, connect an agent, export package-ready SDKs, and keep future updates synced through PR automation.
Guides
Production docs for agent tools.
Use cases
Where teams apply MCP.
Choose your generator
Choose how your agent connects
If your agent supports hosted MCP, connect directly to the generated HTTP endpoint. If your team needs owned client code, export the SDK bundle from the same server.
Install
npm install @modelcontextprotocol/sdk zod
# Optional: pull an owned SDK bundle from Astrail
ASTRAIL_SDK_BUNDLE_URL=https://your-domain.com/api/servers/SERVER_ID/sdk \
ASTRAIL_SDK_OUT_DIR=./generated-sdk \
npm run sdk:pullGenerate endpoint
Send Astrail a real OpenAPI URL or docs page. Astrail discovers the schema, creates endpoint maps, chooses the right tool mode, and stores a hosted MCP server.
OpenAPI to MCP
Swagger UI pages, Redoc pages, YAML, JSON, and docs URLs are normalized into hosted tool metadata.
Website to MCP
Public pages become safe read/search tools with blocked private-network targets and bounded crawl limits.
curl -sS -X POST https://your-domain.com/api/generate \
-H "Content-Type: application/json" \
-d '{
"source_type": "openapi_url",
"source_url": "https://petstore.swagger.io/v2/swagger.json",
"generation_mode": "code"
}'Connect an MCP client
Hosted endpoints expose HTTP JSON-RPC. Start with initialize and tools/list, then call tools through tools/call.
curl -sS -X POST https://your-domain.com/api/mcp/SERVER_ID \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $ASTRAIL_API_KEY" \
-d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'Code Mode
Two tools for large APIs: search_docs and execute.
Large APIs should not flood agent context with hundreds of tools. Code Mode exposes docs search plus no-eval execution. Agents search for the SDK-shaped method, then submit a constrained TypeScript snippet that Astrail compiles to endpoint-map execution.
curl -sS -X POST https://your-domain.com/api/mcp/SERVER_ID \
-H "Content-Type: application/json" \
-d '{
"jsonrpc": "2.0",
"id": 2,
"method": "tools/call",
"params": {
"name": "execute",
"arguments": {
"code": "async function run(client) { return await client.pets.list({ limit: 10 }); }",
"result_mode": "compact"
}
}
}'SDK Factory
Export owned SDKs and docs from the same endpoint.
The hosted MCP endpoint stays the source of truth. SDK exports wrap it with typed clients, docs, manifests, CLI commands, package scaffolds, smoke tests, and GitHub workflows.
ASTRAIL_SDK_BUNDLE_URL=https://your-domain.com/api/servers/SERVER_ID/sdk \
ASTRAIL_SDK_OUT_DIR=./petstore-sdk \
npm run sdk:pull
cd petstore-sdk
node scripts/verify-generated-sdk.mjs
cd typescript
npm install
ASTRAIL_MCP_ENDPOINT=https://your-domain.com/api/mcp/SERVER_ID npm testimport { AstrailClient } from "@astrail/petstore";
const client = new AstrailClient({
endpoint: process.env.ASTRAIL_MCP_ENDPOINT!,
apiKey: process.env.ASTRAIL_API_KEY,
});
await client.initialize();
const docs = await client.searchDocs("list available pets");
const result = await client.execute({
code: "async function run(client) { return await client.pets.list({ limit: 10 }); }",
});from astrail_petstore import AstrailClient
client = AstrailClient(
endpoint="https://your-domain.com/api/mcp/SERVER_ID",
api_key="ASTRAIL_API_KEY",
)
client.initialize()
docs = client.search_docs("list available pets")
result = client.execute(
"async function run(client) { return await client.pets.list({ limit: 10 }); }"
)Generated files
What every SDK bundle contains.
astrail.yamlGeneration config for targets, package names, auth, method hooks, and update automation.
typescript/Typed package scaffold with MCP JSON-RPC client, endpoint helpers, tests, and examples.
python/Python package scaffold with pyproject, endpoint helpers, examples, and smoke tests.
go/, java/, kotlin/Compiled client targets for backend teams and JVM/Go deploy surfaces.
ruby/, csharp/, php/Additional package targets for existing customer ecosystems.
cli/bin/astrail.mjsCommand wrapper for initialize, tools/list, tools/call, search-docs, and execute.
docs/REFERENCE.mdEndpoint reference with SDK method, route, auth, parameters, and runtime behavior.
docs/MCP.mdMCP client setup for Claude, Cursor, local scripts, and hosted HTTP JSON-RPC.
docs/STAINLESS_PARITY.mdEvidence report mapping generated files to production SDK expectations.
mcp/manifest.jsonMachine-readable agent metadata for transport, tools, auth, capabilities, and endpoint map.
openapi/endpoint-catalog.jsonNormalized endpoint catalog for review, diffing, docs, and custom tooling.
.github/workflows/astrail-update.ymlCI workflow that pulls, verifies, tests, and opens SDK update PRs.
Runtime proof
Production behavior is visible, not implied.
Automate updates
Regenerate SDKs through pull requests.
The generated GitHub workflow pulls the latest Astrail bundle, verifies required docs and manifests, runs smoke tests against the hosted MCP endpoint, compiles SDK targets, and opens a review PR.
Publish
Package-manager release stays opt-in.
Review astrail.yaml, connect registry credentials in CI, then publish to npm, PyPI, Maven, RubyGems, NuGet, Packagist, Go modules, or internal registries.
Glossary
MCP reference terms and FAQs.
Reference
HTTP API surface.
/api/spec-previewInspect a docs URL or spec before generation.
/api/generateCreate a hosted MCP server from OpenAPI, Swagger, Redoc, or raw JSON/YAML.
/api/website-to-mcpCreate public website-read MCP tools from a URL.
/api/mcp/:serverIdCall initialize, tools/list, tools/call, search_docs, and execute.
/api/servers/:id/sdkExport owned SDK bundle, docs, CLI, tests, manifests, and workflows.
/api/servers/:id/workerExport a Worker-ready MCP runtime bundle.
/api/credentialsAttach provider credentials for auth-required upstream APIs.
Auth
Protect private endpoints with Astrail API keys.
Public servers can be called without a bearer token. Private servers require Authorization: Bearer ASTRAIL_API_KEY. Upstream provider credentials are attached separately through the credentials API or dashboard.
Limits
Default safety boundaries.
Payloads
Bounded request and response sizes for hosted tools/call.
Execution
No arbitrary eval for Code Mode execute.
Network
Website-to-MCP blocks local/private network targets.
Troubleshooting
Fix common MCP and SDK errors.
Use these runbooks when an endpoint reaches the client but auth, schemas, tool discovery, CORS, limits, or generated SDK builds fail.