Quick Start — MCP

Choose the path that fits your situation. Each one gets you from zero to a working MCP server in your editor in under 5 minutes.

---

Choose Your Path

Install from Hub

Best for: Getting started fast with popular integrations (GitHub, Stripe, Slack, Notion, etc.)

1. Create a workspace

   aerostack workspace create my-workspace
   # -> Gateway URL: https://gateway.aerostack.dev/ws/my-workspace/sse
   # -> Token: mwt_xxxxxxxx (save this)

2. Browse and install an MCP server

   # Search for what you need
   aerostack mcp search "github"
   
   # Install it
   aerostack mcp install @aerostack/github-mcp
   # -> github__create_issue, github__list_pull_requests, ... added to workspace

   Or browse the Hub at aerostack.dev/hub and click Install.

3. Configure secrets (if required)

   Some MCP servers need API keys. The CLI will prompt you:

   # -> This MCP server requires a GitHub token.
   # -> Enter GITHUB_TOKEN: ghp_...
   # -> Secret stored (AES-GCM encrypted). Injected automatically on every tool call.

4. Add the gateway to your editor

   Cursor

   Add to ~/.cursor/mcp.json:

   {
     "mcpServers": {
       "my-workspace": {
         "url": "https://gateway.aerostack.dev/ws/my-workspace/sse",
         "headers": { "Authorization": "Bearer mwt_xxxxxxxx" }
       }
     }
   }

   Claude Desktop

   Add to claude_desktop_config.json:

   {
     "mcpServers": {
       "my-workspace": {
         "type": "sse",
         "url": "https://gateway.aerostack.dev/ws/my-workspace/sse",
         "headers": { "Authorization": "Bearer mwt_xxxxxxxx" }
       }
     }
   }

   VS Code

   Add to .vscode/mcp.json:

   {
     "mcpServers": {
       "my-workspace": {
         "url": "https://gateway.aerostack.dev/ws/my-workspace/sse",
         "headers": { "Authorization": "Bearer mwt_xxxxxxxx" }
       }
     }
   }

5. Use it

   Ask your AI assistant: “Create a GitHub issue titled ‘Fix login bug’ in my repo.”

   The assistant calls github__create_issue through your workspace gateway. Done.

Next: Full Install from Hub guide

Cursor

Best for: Building a custom MCP server with your own business logic, deployed to Cloudflare edge with no infrastructure to manage.

1. Create your MCP server project

   aerostack mcp init my-custom-mcp
   cd my-custom-mcp

   This generates a project with the standard Aerostack MCP structure:

   my-custom-mcp/
     src/
       index.ts          # Tool handlers
     aerostack.json      # MCP configuration
     aerostack.toml      # Cloudflare Worker config
     package.json

2. Define your tools

   Edit src/index.ts:

   import { McpServer } from '@aerostack/mcp';
   
   const server = new McpServer({
     name: 'my-custom-mcp',
     version: '1.0.0',
   });
   
   server.tool('lookup_customer', {
     description: 'Look up a customer by email address',
     inputSchema: {
       type: 'object',
       properties: {
         email: { type: 'string', description: 'Customer email address' },
       },
       required: ['email'],
     },
     handler: async ({ email }, env) => {
       const result = await env.DB.prepare(
         'SELECT * FROM customers WHERE email = ?'
       ).bind(email).first();
   
       return {
         content: [{ type: 'text', text: JSON.stringify(result) }],
       };
     },
   });
   
   export default server;

3. Deploy

   aerostack deploy mcp
   # -> Deployed to Cloudflare edge
   # -> MCP URL: https://mcp-my-custom-mcp.aerostack.dev

4. Add to your workspace

   aerostack mcp install my-custom-mcp --workspace my-workspace

5. Use it

   Your editor already has the workspace gateway configured. The new tool appears automatically:

   my-custom-mcp__lookup_customer

Next: Full Host on Aerostack guide

Claude Desktop

Best for: Teams that already run MCP servers on their own infrastructure and want centralized secret management, access control, and analytics.

1. Register your MCP server

   In the Admin dashboard, go to MCP Servers and click Add External MCP. Enter:

   • Name: My Internal API
   • External URL: https://mcp.internal.yourcompany.com/sse
   • Slug: internal-api

   Or via CLI:

   aerostack mcp register \
     --name "My Internal API" \
     --url "https://mcp.internal.yourcompany.com/sse" \
     --slug internal-api

2. Store secrets

   aerostack secrets set internal-api API_KEY "sk-your-production-key"
   aerostack secrets set internal-api AUTH_HEADER "Bearer sk-your-production-key"
   # -> Secrets stored (AES-GCM encrypted). Injected as headers on every request.

3. Add to your workspace

   aerostack mcp install internal-api --workspace my-workspace

4. Share with your team

   Issue tokens for each team member:

   aerostack workspace token create my-workspace --name "Alice"
   # -> mwt_alice_xxxxxxxx

   Alice adds the workspace URL to her editor. She connects to the gateway. The gateway injects the production API key. Alice never sees it.

Next: Full Proxy Existing MCP guide

---

What Happens Next

Whichever path you chose, you now have:

• A workspace gateway URL configured in your editor
• One or more MCP servers connected
• Tools available to your AI assistant

From here:

• Add more MCP servers to the same workspace
• Invite team members with per-user tokens
• Configure secrets for secure key management
• Monitor usage per user

Note

Every MCP server you add appears in your editor automatically. No config changes needed after initial setup.