Astrail docs
Quickstart
Give an agent secure access to third-party SaaS with per-user consent, encrypted grants, scope enforcement, permissions, and audit logs. Bring your own tool contract, import MCP, or generate from OpenAPI and GraphQL.
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: download an owned SDK bundle from Astrail
curl --fail --location \
-H "Authorization: Bearer $ASTRAIL_API_KEY" \
"https://your-domain.com/api/servers/SERVER_ID/sdk?format=tgz" \
--output generated-sdk.tar.gzGenerate endpoint
Open the authenticated generator, paste a real OpenAPI URL, and review the discovered tools before saving. The generation API requires your signed-in workspace session and abuse challenge; it is not an unauthenticated public cURL endpoint.
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.
{
"sourceType": "openapi_url",
"sourceUrl": "https://petstore.swagger.io/v2/swagger.json",
"generationMode": "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.
curl --fail --location \
-H "Authorization: Bearer $ASTRAIL_API_KEY" \
"https://your-domain.com/api/servers/SERVER_ID/sdk?format=tgz" \
--output petstore-sdk.tar.gz
mkdir -p petstore-sdk
tar -xzf petstore-sdk.tar.gz -C petstore-sdk
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-regenerate.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/oauth/connectStart per-user provider consent with PKCE and encrypted token storage.
/api/x402/domainsCreate an HTTPS ownership challenge for a paid upstream domain.
/api/x402/domains/:id/verifyVerify the upstream domain before payment proofs can be forwarded.
/api/x402/receiptsList non-custodial payment reservations and settlement receipts.
/api/credentialsAttach provider credentials for auth-required upstream APIs.
/api/credentials/:idRemove a stored provider connection so it can no longer be injected.
Auth
Separate caller identity from provider identity.
Private servers require Authorization: Bearer ASTRAIL_API_KEY. Bind that key to an end user and actor role, then connect a separate provider grant through hosted OAuth. Astrail never relays the caller bearer token upstream and withholds provider tokens when required scopes are missing. Read the OAuth security model.
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.