# Quick Start — MCP

> Get your first MCP server running on Aerostack in under 5 minutes. Choose your path — install from Hub, host your own, or proxy an existing server.

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

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

1. **Create a workspace**

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

1. **Browse and install an MCP server**

   ```bash
   # 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](https://aerostack.dev/hub) and click **Install**.

1. **Configure secrets (if required)**

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

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

1. **Add the gateway to your editor**

   

   
   Add to `~/.cursor/mcp.json`:

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

   
   Add to `claude_desktop_config.json`:

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

   
   Add to `.vscode/mcp.json`:

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

   

1. **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](/mcp/install-from-hub)

**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**

   ```bash
   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
   ```

1. **Define your tools**

   Edit `src/index.ts`:

   ```typescript
   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;
   ```

1. **Deploy**

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

1. **Add to your workspace**

   ```bash
   aerostack mcp install my-custom-mcp --workspace my-workspace
   ```

1. **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](/mcp/host-on-aerostack)

**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:

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

1. **Store secrets**

   ```bash
   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.
   ```

1. **Add to your workspace**

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

1. **Share with your team**

   Issue tokens for each team member:

   ```bash
   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](/mcp/proxy-existing)

---

## 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](/mcp/install-from-hub) to the same workspace
- [Invite team members](/mcp/team-management) with per-user tokens
- [Configure secrets](/mcp/secrets-security) for secure key management
- [Monitor usage](/mcp/team-management#per-user-analytics) per user

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