Dev astroMCP

What Dev astroMCP is

Dev astroMCP is a small Node/TypeScript MCP server over stdio.

In the dev profile it exposes five developer-productivity tools:

• dev.list_allowed — shows the exact { method, path } operations that are allowed
• dev.get_schema — fetches OpenAPI or llm_v2 schemas for an endpoint to understand request/response shapes
• dev.fetch_lab_preset — retrieves pre-configured payloads from Chart Studio Lab (minimal, balanced, everything)
• dev.search_docs — searches documentation to find integration guidance and best practices
• dev.call — calls one allowed operation by { method, path, query?, body? }

What it is not

Dev astroMCP is intentionally limited:

• Not an agent orchestrator
• Not a control plane surface
• Not an API key management surface
• Not a mechanism to automatically "discover" new endpoints

If an operation is not explicitly allowlisted, it cannot be called.

mcp-compatible clients

Dev astroMCP is meant to be used from mcp-compatible clients (MCP hosts).

Examples:

• Cursor (IDE)
• VS Code (via an MCP client extension)
• Claude Desktop (desktop app)
• MCP Inspector (developer tool for testing MCP servers)

You can also use other MCP hosts that support stdio servers.

IDE setup

These steps are intentionally simple and explicit. The exact UI labels can vary by client version.

Cursor

1. Open Cursor settings for MCP servers.
2. Add a new stdio MCP server.
3. Point it at your local Dev astroMCP server command.
4. Provide environment variables (see Quick start below).
5. Verify by running dev.list_allowed.

VS Code

VS Code does not include an MCP client by default. Use an MCP client extension.

Examples (non-exhaustive):

• Continue
• Cline

General steps:

1. Install an MCP client extension.
2. Add a stdio MCP server entry for Dev astroMCP.
3. Provide environment variables (see Quick start below).
4. Verify by running dev.list_allowed.

Safety model (default-deny)

Calls are default-deny:

• Only operations on the allowlist can be executed.
• The tool surface does not silently expand when the backend changes.

Quick start (local)

You run the Dev astroMCP server locally and point your client at it.

Recommended Developer Workflow

The five tools work together to support a test-first approach:

1. Discover: Use dev.list_allowed to see what endpoints you can call
2. Understand: Use dev.get_schema to fetch the OpenAPI schema for your target endpoint
3. Seed: Use dev.fetch_lab_preset to get pre-built payloads (minimal/balanced/everything presets)
4. Learn: Use dev.search_docs to find integration guides and best practices
5. Execute: Use dev.call only after you've confirmed the format and payload

Pro Tip: Use Astro Lab First

Before using Dev astroMCP, test your payloads interactively in Astro Lab:

• Build and validate requests in the visual form builder
• Switch to "Code Lens" to see the exact JSON
• Copy the tool call to use with dev.call in your AI agent

Environment Setup

Required environment:

• ASTROMCP_PROFILE=dev
• ASTROMCP_BACKEND_URL=<backend base url>

Authentication (choose one):

• ASTROMCP_API_KEY=<api key> (sent as X-API-Key)
• ASTROMCP_JWT=<jwt> (sent as Authorization: Bearer ..., legacy)

Verification:

1. Connect your MCP client.
2. Run dev.list_allowed.
3. Confirm the operation you need is listed before calling dev.call.

Tool reference

dev.list_allowed

Use this to confirm exactly what the server will allow.

When to use: First, to discover available endpoints.

dev.get_schema

Fetch OpenAPI or LLM-optimized schema for a specific endpoint.

Inputs:

• path: absolute path starting with / (required)
• format: openapi (default) or llm_v2 (compact for LLMs)
• include_components: boolean, whether to include referenced schema components (default: true)

Output: Full OpenAPI operation definition or LLM-optimized schema with request/response shapes.

When to use: After list_allowed, to understand what fields an endpoint expects.

Example:

Use dev.get_schema:
- path: /ephemeris/natal-chart
- format: llm_v2

dev.fetch_lab_preset

Retrieve pre-configured Chart Studio Lab payloads.

Inputs:

• preset_name: optional preset name (minimal, balanced, everything) or omit to list all

Output: Ready-to-use JSON payload or list of available presets.

When to use: After understanding the schema, to seed your request with sample data.

Example:

Use dev.fetch_lab_preset:
- preset_name: balanced

dev.search_docs

Search documentation for integration guidance and best practices.

Inputs:

• query: search term or question

Output: Matching documentation snippets with titles and descriptions.

When to use: Anytime you need guidance on integration patterns, setup, or troubleshooting.

Example:

Use dev.search_docs:
- query: "how to use natal chart for LLM agent"

dev.call

Use this to call an allowlisted backend endpoint.

Inputs:

• method: GET|POST|PUT|PATCH|DELETE
• path: absolute path starting with /
• query: optional query params
• body: optional JSON body

If you see "Denied operation", the { method, path } pair is not on the allowlist.

Installation, examples, troubleshooting

• Installation guide
• Usage examples
• Troubleshooting