Skip to main content
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)
  • An LLM API key (Gemini recommended for best results)
Don’t have an LLM of choice? You can get a free Gemini API key here and use “google/gemini-2.5-pro” to get started!

​
Step 1: Install MCPKit

Install MCPKit globally using npm: 
npm install -g @kevinoconnell/mcpkit
Verify the installation: 
mcpkit version
You should see the version number printed to the console.

​
Step 2: Configure API Keys

Run the secrets setup command: 
mcpkit secrets
You’ll be prompted to enter:
  1. Browserbase API key - Get yours at browserbase.com
  2. LLM provider and API key - Choose from:
    • Google Gemini (recommended)
    • OpenAI
    • Anthropic
    • Azure OpenAI
We recommend using Google Gemini 2.5 pro for the best balance of speed and quality.
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: 
mcpkit create https://news.ycombinator.com
1

Website Analysis

MCPKit will launch a browser session and analyze the website to discover available actions.
This step uses Browserbase to run a headless browser in the cloud, so you don’t need Chrome installed locally.
2

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.
3

Action Discovery

MCPKit will automatically discover actions like:
  • Searching for articles
  • Reading article content
  • Extracting comments
  • Navigating pages
4

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
Your MCP server has been successfully generated!

​
Step 4: Test Your MCP Server

Navigate to the generated folder: 
cd mcp-stagehand-news.ycombinator.com
Install dependencies: 
npm install
Build the server: 
npm run build
Test with the MCP Inspector: 
npx @modelcontextprotocol/inspector node dist/index.js
MCP Inspector showing Hacker News server tools
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: 
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”
Make sure to provide the absolute path to dist/index.js if you’re adding the server from a different directory.

​
What’s Next?

Explore CLI Commands

Learn about all available MCPKit commands

View Examples

See example MCP servers for different websites

Manage Contexts

Learn how to save and reuse authentication contexts

Advanced Features

Customize and extend your MCP servers

​
Common Issues

Make sure your Browserbase API key is valid and you have an active internet connection.
# Check your secrets
mcpkit secrets show
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
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
Authentication contexts are stored per domain. Make sure:
  • You completed the authentication flow
  • The domain matches (www.example.com vs example.com)
  • You have write permissions to ~/.mcpkit/contexts/

​
Need Help?

Join Discord

Get help from the community

GitHub Issues

Report bugs or request features