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

# Quickstart

> Create your first MCP server in 5 minutes

This guide will walk you through creating your first MCP server using MCPKit. You'll generate a server for Hacker News that can search and extract articles.

## Prerequisites

Before you begin, you'll need:

* Node.js 18 or later installed
* A Browserbase API key ([sign up here](https://www.browserbase.com))
* An LLM API key (Gemini recommended for best results)

<Note>
  Don't have an LLM of choice? You can get a free Gemini API key [here](https://aistudio.google.com/api-keys) and use "google/gemini-2.5-pro" to get started!
</Note>

## Step 1: Install MCPKit

Install MCPKit globally using npm:

```bash theme={null}
npm install -g @kevinoconnell/mcpkit
```

Verify the installation:

```bash theme={null}
mcpkit version
```

<Check>
  You should see the version number printed to the console.
</Check>

## Step 2: Configure API Keys

Run the secrets setup command:

```bash theme={null}
mcpkit secrets
```

You'll be prompted to enter:

1. **Browserbase API key** - Get yours at [browserbase.com](https://www.browserbase.com)
2. **LLM provider and API key** - Choose from:
   * Google Gemini (recommended)
   * OpenAI
   * Anthropic
   * Azure OpenAI

<Tip>
  We recommend using Google Gemini 2.5 pro for the best balance of speed and quality.
</Tip>

Your credentials are stored securely in:

* macOS/Linux: `~/.mcpkit/secrets.json`
* Windows: `%USERPROFILE%\.mcpkit\secrets.json`

## Step 3: Create Your First MCP Server

Let's create an MCP server for Hacker News:

```bash theme={null}
mcpkit create https://news.ycombinator.com
```

<Steps>
  <Step title="Website Analysis">
    MCPKit will launch a browser session and analyze the website to discover available actions.

    <Info>
      This step uses Browserbase to run a headless browser in the cloud, so you don't need Chrome installed locally.
    </Info>
  </Step>

  <Step title="Authentication (Optional)">
    If the website requires authentication, you'll be prompted to log in through a live browser session.

    ```
    🔐 This site may require authentication.
    Would you like to authenticate? (Y/n)
    ```

    Your authentication context will be saved for future use.
  </Step>

  <Step title="Action Discovery">
    MCPKit will automatically discover actions like:

    * Searching for articles
    * Reading article content
    * Extracting comments
    * Navigating pages
  </Step>

  <Step title="Server Generation">
    A complete MCP server will be generated in a new folder:

    ```
    📁 mcp-stagehand-news.ycombinator.com/
    ├── src/
    │   ├── index.ts        # Main MCP server
    │   └── tools/          # Generated tools
    ├── package.json
    └── tsconfig.json
    ```
  </Step>
</Steps>

<Check>
  Your MCP server has been successfully generated!
</Check>

## Step 4: Test Your MCP Server

Navigate to the generated folder:

```bash theme={null}
cd mcp-stagehand-news.ycombinator.com
```

Install dependencies:

```bash theme={null}
npm install
```

Build the server:

```bash theme={null}
npm run build
```

Test with the MCP Inspector:

```bash theme={null}
npx @modelcontextprotocol/inspector node dist/index.js
```

<Frame>
  <img src="https://mintlify.s3.us-west-1.amazonaws.com/agentflow-427edd42/HNMCP.png" alt="MCP Inspector showing Hacker News server tools" />
</Frame>

You should see a list of available tools that the AI can use to interact with Hacker News.

## Step 5: Use with Claude Code

To use your MCP server with Claude Code, add it to your MCP configuration:

```bash theme={null}
claude mcp add --transport stdio "hackernews" -- node dist/index.js
```

Now you can ask Claude to:

* "Search Hacker News for articles about AI"
* "Get me the top story from Hacker News"
* "Find discussions about React on HN"

<Tip>
  Make sure to provide the absolute path to `dist/index.js` if you're adding the server from a different directory.
</Tip>

## What's Next?

<CardGroup cols={2}>
  <Card title="Explore CLI Commands" icon="terminal" href="/commands/create">
    Learn about all available MCPKit commands
  </Card>

  <Card title="View Examples" icon="book" href="/examples/overview">
    See example MCP servers for different websites
  </Card>

  <Card title="Manage Contexts" icon="database" href="/commands/contexts">
    Learn how to save and reuse authentication contexts
  </Card>

  <Card title="Advanced Features" icon="wand-magic-sparkles" href="/advanced/custom-tools">
    Customize and extend your MCP servers
  </Card>
</CardGroup>

## Common Issues

<AccordionGroup>
  <Accordion title="Browser session fails to connect" icon="wifi">
    Make sure your Browserbase API key is valid and you have an active internet connection.

    ```bash theme={null}
    # Check your secrets
    mcpkit secrets show
    ```
  </Accordion>

  <Accordion title="Action discovery finds no actions" icon="magnifying-glass">
    Some websites have dynamic content that loads slowly. Try:

    * Using a more specific URL (e.g., a specific page rather than the homepage)
    * Ensuring the website is accessible and not behind a paywall
    * Checking if the website requires authentication
  </Accordion>

  <Accordion title="Generated server doesn't work" icon="triangle-exclamation">
    Common fixes:

    * Make sure you ran `npm install` and `npm run build`
    * Check that Node.js version is 18 or later
    * Verify your Browserbase API key is still valid
    * Try regenerating the server with `mcpkit create` again
  </Accordion>

  <Accordion title="Authentication context not saving" icon="lock">
    Authentication contexts are stored per domain. Make sure:

    * You completed the authentication flow
    * The domain matches ([www.example.com](http://www.example.com) vs example.com)
    * You have write permissions to `~/.mcpkit/contexts/`
  </Accordion>
</AccordionGroup>

## Need Help?

<CardGroup cols={2}>
  <Card title="Join Discord" icon="discord" href="https://discord.gg/ASQJAxzM">
    Get help from the community
  </Card>

  <Card title="GitHub Issues" icon="github" href="https://github.com/kevoconnell/mcpkit/issues">
    Report bugs or request features
  </Card>
</CardGroup>