> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metamcp.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Get MetaMCP running in minutes and configure your first MCP servers

Get MetaMCP up and running in just a few minutes and configure your first MCP server aggregation.

## Prerequisites

Before starting, ensure you have:

* Docker and Docker Compose installed
* Git for cloning the repository
* Basic understanding of MCP (Model Context Protocol)

## Step 1: Installation

<AccordionGroup>
  <Accordion icon="github" title="Clone the Repository">
    Clone MetaMCP from GitHub and navigate to the project directory:

    ```bash theme={null}
    git clone https://github.com/metatool-ai/metamcp.git
    cd metamcp
    ```
  </Accordion>

  <Accordion icon="settings" title="Configure Environment">
    Copy the example environment file and customize as needed:

    ```bash theme={null}
    cp example.env .env
    ```

    <Note>
      If you modify `APP_URL` in the `.env` file, make sure you only access MetaMCP from that URL due to CORS policy enforcement.
    </Note>

    <Warning>In production environment, make sure you modify POSTGRES\_PASSWORD and BETTER\_AUTH\_SECRET. Also use HTTPS. A typical way to generate secrets is `openssl rand -hex 32 | base64`</Warning>
  </Accordion>

  <Accordion icon="docker" title="Start with Docker Compose">
    Launch MetaMCP using Docker Compose:

    ```bash theme={null}
    docker compose up -d
    ```

    This will start:

    * MetaMCP fullstack docker image
    * PostgreSQL database

    <Tip>
      The first startup may take a few minutes as Docker images are pulled and downloaded.
    </Tip>
  </Accordion>
</AccordionGroup>

## Step 2: Access MetaMCP

Once the containers are running:

1. **Open your browser** and go to `http://localhost:12008` (or your configured `APP_URL`)
2. **Create an account** or log in
3. **Explore the dashboard** - you'll see sections for MCP Servers, Namespaces, and Endpoints
4. **(Optional) Disable signup** You may only allow you and your team access MetaMCP, so once you setup the accounts, you can disable new user registration in Settings page.

## Step 3: Configure Your First MCP Server

<AccordionGroup>
  <Accordion icon="server" title="Step 3.1: Add a MCP Server">
    1. Navigate to **MCP Servers** in the sidebar (or you can quickly add one from **Explore & Search** page)
    2. Click **"Add Server"** button (top right)
    3. In the dialog that opens, fill out the server configuration:

    **Basic Information:**

    * **Name**: `hackernews-server` (must be URL-compatible: letters, numbers, underscores, hyphens only)
    * **Description**: `HackerNews MCP server for fetching stories and comments`
    * **Type**: Select `STDIO` from dropdown

    **Server Configuration:**

    * **Command**: `uvx`
    * **Arguments**: `mcp-hn` (space-separated arguments)
    * **Environment Variables**: Leave empty (format: `KEY=value`, one per line)

    **Ownership:**

    * Choose **"For myself (Private)"** or **"Everyone (Public)"**
    * Private servers are only accessible to you
    * Public servers are accessible to all users

    4. Click **"Create Server"**
    5. You should see a success message: "MCP Server Created"

    <Note>
      After creating the server, you can click on it to view details, test the connection, and see available tools.
    </Note>
  </Accordion>

  <Accordion icon="package" title="Step 3.2: Create a Namespace">
    **Why Namespaces?** Namespaces group multiple MCP servers together and provide a unified endpoint for external access.

    1. Go to **Namespaces** in the sidebar
    2. Click **"Create Namespace"** button (top right)
    3. Fill out the namespace form:

    **Basic Information:**

    * **Name**: `news-information` (descriptive name for your server group)
    * **Description**: `Namespace containing news and information retrieval tools`

    **Ownership:**

    * Choose **"For myself (Private)"** or **"Everyone (Public)"**

    **Select MCP Servers:**

    * You'll see a list of available MCP servers with checkboxes
    * Check the box next to your **"hackernews-server"**
    * You can select multiple servers for one namespace
    * Each server shows its type (STDIO, SSE, etc.) and description

    4. Click **"Create Namespace"**
    5. Success message: "Namespace Created"

    <Tip>
      You can add or remove servers from a namespace later by editing it.
    </Tip>
  </Accordion>
</AccordionGroup>

## Step 4: Manage Tools in Your Namespace

<AccordionGroup>
  <Accordion icon="wrench" title="Review and Disable Unused Tools">
    **Why Manage Tools?** Each MCP server may expose many tools, but you might only want to make certain tools available through your endpoint.

    1. Go to **Namespaces** in the sidebar
    2. Click on your **"news-information"** namespace to view details
    3. You'll see three main sections:

    **Connection Status:**

    * Check if the namespace can connect to its MCP servers
    * Green status means all servers are reachable
    * Click **"Connect"** if needed to establish connection

    **MCP Servers:**

    * View all servers assigned to this namespace
    * See server status (Active/Inactive/Error)
    * Monitor server health and configuration

    **Tools Management:**

    * See all tools available from your servers
    * Each tool shows:
      * **Tool name** (e.g., `get_top_stories`, `get_story`)
      * **Source server** (which server provides this tool)
      * **Description** and input schema
      * **Status** (enabled/disabled)

    4. **Disable unwanted tools:**

    * Uncheck tools you don't want to expose via the endpoint
    * For example, you might keep `get_top_stories` but disable `get_user_info`
    * This helps keep your endpoint focused and secure

    5. **Refresh Tools** if needed to get latest tools from servers

    <Note>
      Only enabled tools will be available when external applications use your endpoint.
    </Note>
  </Accordion>
</AccordionGroup>

## Step 5: Create an Endpoint

<AccordionGroup>
  <Accordion icon="link" title="Create Your Public Endpoint">
    **What are Endpoints?** Endpoints provide external access to your namespaces via HTTP APIs that other applications can consume.

    1. Navigate to **Endpoints** in the sidebar
    2. Click **"Create Endpoint"** button (top right)
    3. Configure your endpoint:

    **Basic Information:**

    * **Name**: `news-endpoint` (URL-compatible name - this becomes `/metamcp/news-endpoint`)
    * **Description (Optional)**: `Public endpoint for news and information tools`

    **Ownership:**

    * Choose **"For myself (Private)"** or **"Everyone (Public)"**

    **Namespace Selection:**

    * Click the **"Select a namespace"** dropdown
    * Choose your **"news-information"** namespace
    * You'll see the namespace name and description in the dropdown

    **API Key Authentication:**

    * **Enable API Key Authentication**: Toggle ON (recommended)
      * This requires API keys for endpoint access
    * **Use Query Parameter Authentication**: Toggle ON/OFF
      * When ON: Allows `?api_key=xxx` in URLs
      * When OFF: Only accepts API keys in `Authorization: Bearer xxx` headers

    **MCP Server Creation:**

    * **"Automatically create an MCP server for this endpoint"**: Check this box
    * This creates a Streamable HTTP MCP server configuration for inspection

    4. Click **"Create Endpoint"**
    5. Success message: "Endpoint Created"

    **Your endpoint will be available at:**

    * SSE: `http://localhost:12008/metamcp/news-endpoint/sse`
    * Streamable HTTP: `http://localhost:12008/metamcp/news-endpoint/mcp`
    * OpenAPI: `http://localhost:12008/metamcp/news-endpoint/api`
    * Schema: `http://localhost:12008/metamcp/news-endpoint/api/openapi.json`
  </Accordion>
</AccordionGroup>

## Step 6: Generate API Key

<AccordionGroup>
  <Accordion icon="key" title="Create API Key">
    1. Go to **API Keys** in the sidebar
    2. Click **"Generate Key"** button
    3. Fill out the API key form:

    **Key Information:**

    * **Description**: `My first MetaMCP API key for news endpoint`
    * **Scope**:
      * **Private**: Only you can use this key
      * **Public**: All users can use this key

    4. Click **"Generate Key"**
    5. **Important**: Copy and save the key securely - it starts with `sk_mt_`
    6. This key will be used to authenticate requests to your endpoints

    <Warning>
      The API key is only shown once. Make sure to copy it immediately.
    </Warning>
  </Accordion>
</AccordionGroup>

## Step 7: Managing Your Configuration

<AccordionGroup>
  <Accordion icon="settings" title="Managing MCP Servers">
    **View Server Details:**

    * Click on any server in the MCP Servers list
    * See connection status, available tools, and configuration
    * Test server connection and inspect tools

    **Edit Servers:**

    * Use the actions menu (⋯) next to each server
    * Modify configuration, add environment variables
    * Update commands and arguments

    **Server States:**

    * **Active**: Server is running and available
    * **Inactive**: Server is configured but not running
    * **Error**: Server has connection issues
  </Accordion>

  <Accordion icon="layers" title="Managing Namespaces">
    **View Namespace Details:**

    * Click on any namespace to see its servers and tools
    * Monitor which servers are active in the namespace
    * View aggregated tools from all servers

    **Edit Namespaces:**

    * Add or remove servers from existing namespaces
    * Update name and description
    * Change ownership settings

    **Tool Management:**

    * See all tools available across servers in the namespace
    * Enable/disable specific tools
    * View tool schemas and documentation
  </Accordion>

  <Accordion icon="link" title="Managing Endpoints">
    **Endpoint URLs:**
    Each endpoint provides multiple access methods:

    * **SSE**: Server-Sent Events for real-time communication
    * **Streamable HTTP**: HTTP-based MCP communication
    * **OpenAPI**: REST API with OpenAPI documentation
    * **Schema**: OpenAPI JSON schema for integration

    **Copy URLs:**

    * Use the actions menu (⋯) to copy specific URLs
    * Copy URLs with or without embedded API keys
    * Use different formats for different integrations

    **Edit Endpoints:**

    * Change which namespace an endpoint maps to
    * Update authentication settings
    * Modify access permissions
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Add More Servers" icon="plus" href="/en/concepts/mcp-servers">
    Learn how to configure different types of MCP servers (STDIO, HTTP, etc.)
  </Card>

  <Card title="Configure Middleware" icon="filter" href="/en/concepts/middleware">
    Apply middleware to filter tools and transform requests/responses
  </Card>

  <Card title="Connect to Cursor" icon="mouse-pointer-2" href="/en/integrations/cursor">
    Configure Cursor IDE to use your MetaMCP endpoints
  </Card>

  <Card title="Connect to Claude Desktop" icon="monitor-dot" href="/en/integrations/claude-desktop">
    Set up Claude Desktop with MetaMCP using mcp-proxy
  </Card>
</CardGroup>

## Troubleshooting

<AccordionGroup>
  <Accordion icon="warning" title="Common Issues">
    **CORS errors**: Ensure you're accessing MetaMCP from the URL specified in `APP_URL`.

    **Database connection**: Check that PostgreSQL container is running with `docker ps`.

    **Memory issues**: MetaMCP requires at least 2GB RAM for optimal performance.

    **Server connection failures**: Check MCP server logs in the server detail pages.

    **Authentication issues**: Verify API keys are active and correctly formatted.
  </Accordion>

  <Accordion icon="question" title="Need Help?">
    * Browse [GitHub Issues](https://github.com/metatool-ai/metamcp/issues)
    * Join our [Discord community](https://discord.gg/mNsyat7mFX)
  </Accordion>
</AccordionGroup>