# Authentication
Source: https://mcpkit.sh/advanced/authentication
Advanced guide to handling authentication in MCPKit generated MCP servers
Learn how MCPKit handles authentication, manages browser contexts, and secures your credentials.
## How Authentication Works
MCPKit uses Browserbase's persistent context feature to save and reuse authentication sessions:
When you first create an MCP server for an authenticated site, MCPKit opens a live browser session where you can log in normally.
The browser context ID is saved to `~/.mcpkit/contexts/.txt`
Future MCP server executions load the saved context, so you don't need to log in again.
## Authentication Flow
### For End Users
When using an MCPKit generated MCP server:
```bash theme={null}
# First time: Authenticate
mcpkit create https://mcpkit.sh
# Complete login in browser
# Server uses saved context automatically
# No re-authentication needed!
```
### For Developers
In generated servers (`src/index.ts`):
```typescript theme={null}
/**
* Get saved context ID from mcpkit contexts
*/
async function getSavedContextId(domain: string): Promise {
const contextFilePath = path.join(
os.homedir(),
".mcpkit",
"contexts",
`${domain}.txt`
);
try {
const contextId = await fs.readFile(contextFilePath, "utf-8");
return contextId.trim();
} catch {
return null; // No saved context
}
}
// Initialize Stagehand with saved or new context
const contextId = await getSavedContextId("mcpkit.sh");
const stagehand = new Stagehand({
env: "BROWSERBASE",
apiKey: process.env.BROWSERBASE_API_KEY!,
projectId: process.env.BROWSERBASE_PROJECT_ID!,
contextId: contextId || undefined, // Use saved context if available
});
```
## Managing Contexts
### View Saved Contexts
```bash theme={null}
mcpkit contexts list
```
### Create New Context
```bash theme={null}
mcpkit contexts create mcpkit.sh
```
### Delete Context
```bash theme={null}
mcpkit contexts delete mcpkit.sh
```
### Show Context Details
```bash theme={null}
mcpkit contexts show mcpkit.sh
```
## Security Best Practices
Authentication contexts contain sensitive session data. Follow these practices
to keep them secure.
### 1. Protect Context Files
```bash theme={null}
# Check permissions
ls -la ~/.mcpkit/contexts/
# Should be 600 (readable only by you)
chmod 600 ~/.mcpkit/contexts/*.txt
```
### 2. Use Separate Accounts
For automation, create dedicated service accounts:
```
automation@company.com - For internal tool MCPs
bot@company.com - For public service MCPs
```
### 3. Rotate Contexts Regularly
```bash theme={null}
# Weekly rotation example
mcpkit contexts delete mcpkit.sh
mcpkit contexts create mcpkit.sh
```
### 4. Never Commit Contexts
Add to `.gitignore`:
```gitignore theme={null}
.mcpkit/
*.context
*_context.txt
```
## Common Authentication Types
### OAuth / SSO
Many modern tools use OAuth or SSO:
```bash theme={null}
mcpkit create https://mcpkit.sh
# Opens browser -> Login with Google/GitHub
# MCPKit saves the resulting session
```
**Supported:**
* Google OAuth
* GitHub OAuth
* Microsoft OAuth
* SAML SSO
* Custom OAuth providers
### Username & Password
Traditional login forms:
```bash theme={null}
mcpkit create https://oldschool-tool.com
# Opens browser -> Enter username/password
# Complete any 2FA if required
# MCPKit saves session
```
### API Keys
Some tools use API key authentication:
```typescript theme={null}
// In generated server, you can customize to use API keys
const response = await fetch("https://api.example.com/data", {
headers: {
Authorization: `Bearer ${process.env.API_KEY}`,
},
});
```
For API-first tools, you might not need browser automation at all. Consider
using the native API directly.
### Multi-Factor Authentication (2FA)
MCPKit fully supports 2FA:
```bash theme={null}
mcpkit create https://secure-app.com
# Login normally
# Complete 2FA (SMS, authenticator app, etc.)
# Wait until fully logged in
# Press Enter to save context
```
## Troubleshooting Authentication
If your saved context stops working:
```bash theme={null}
# Delete old context
mcpkit contexts delete example.com
# Create new one
mcpkit contexts create example.com
```
**Why it happens:**
* Session tokens have expiration dates
* Password changes invalidate sessions
* Security policies force re-authentication
If the browser keeps asking you to log in:
1. **Complete all authentication steps** - Don't press Enter until fully logged in
2. **Check for redirects** - Wait for final landing page
3. **Verify cookies** - Some sites use complex cookie setups
4. **Try incognito** - Clear any conflicting sessions
```bash theme={null}
# Start fresh
mcpkit contexts delete example.com
# Try in a clean browser state
mcpkit contexts create example.com
```
If two-factor authentication fails:
1. **Use authenticator apps** over SMS when possible
2. **Complete before pressing Enter** - Don't rush the process
3. **Check for "remember this device"** - Enable if available
4. **Verify time sync** - TOTP codes require accurate system time
If tools fail with permission errors:
1. **Check account permissions** - Verify you have necessary access rights
2. **Try different account** - Use an admin account if needed
3. **Review workspace settings** - Some features may be restricted
4. **Contact admin** - Request necessary permissions
## Advanced Patterns
### Context Sharing (Team Use)
For authorized internal tools only:
```bash theme={null}
# Export context ID
cat ~/.mcpkit/contexts/internal-tool.com.txt
# Share with team (securely)
# They save it to their own ~/.mcpkit/contexts/internal-tool.com.txt
```
Only share contexts for authorized service accounts on internal tools. Never
share personal account contexts.
### Conditional Authentication
Check if authentication is needed:
```typescript theme={null}
async function ensureAuthenticated() {
const contextId = await getSavedContextId(DOMAIN);
if (!contextId) {
throw new Error(
`No saved context for ${DOMAIN}. Run: mcpkit contexts create ${DOMAIN}`
);
}
return contextId;
}
```
### Session Refresh
Automatically refresh sessions:
```typescript theme={null}
async function refreshSessionIfNeeded(stagehand: Stagehand) {
const page = stagehand.context.pages()[0];
// Check if still logged in
const isLoggedIn = await stagehand.extract(
"check if user is logged in",
z.boolean()
);
if (!isLoggedIn) {
throw new Error("Session expired. Please re-authenticate.");
}
}
```
## Environment Variables
Store sensitive data in environment variables:
```bash theme={null}
# .env in generated server
BROWSERBASE_API_KEY=bb_xxxxx
BROWSERBASE_PROJECT_ID=xxxxx
BROWSERBASE_CONTEXT_ID=ctx_xxxxx # Optional: override saved context
# Application credentials (if needed)
APP_USERNAME=automation@company.com
APP_API_KEY=secret_key_here
```
## Next Steps
Learn about the contexts command
Customize authentication in generated servers
# Use with Claude Code
Source: https://mcpkit.sh/advanced/claude-code
Integrate your MCPKit generated MCP servers with Claude Code
## Overview
Claude Code is an AI-powered coding assistant that supports the Model Context Protocol (MCP). Once you've generated an MCP server with MCPKit, you can integrate it with Claude Code to give Claude the ability to interact with websites directly from your development environment.
## Prerequisites
Before you begin, make sure you have:
* Claude Code installed (available via VS Code extension or desktop app)
* An MCPKit generated MCP server built and ready to use
* The absolute path to your MCP server's `dist/index.js` file
If you haven't created an MCP server yet, check out our [Quickstart Guide](/quickstart) to generate your first server in minutes.
## Adding Your MCP Server to Claude Code
### Step 1: Build Your MCP Server
Navigate to your generated MCP server directory and build it:
```bash theme={null}
cd mcp-stagehand-yoursite.com
npm install
npm run build
```
Verify that the `dist/index.js` file was created successfully.
### Step 2: Add to Claude Code
Use the Claude Code CLI to add your MCP server:
```bash theme={null}
claude mcp add --transport stdio "your-server-name" -- node /absolute/path/to/dist/index.js
```
Replace:
* `your-server-name` with a descriptive name (e.g., "hackernews", "notion", "jira")
* `/absolute/path/to/dist/index.js` with the full path to your built server
Always use absolute paths when configuring MCP servers. Relative paths may not work correctly.
### Example
```bash theme={null}
# Add a Hacker News MCP server
claude mcp add --transport stdio "hackernews" -- node /Users/yourname/mcp-servers/mcp-stagehand-news.ycombinator.com/dist/index.js
# Add a Notion MCP server
claude mcp add --transport stdio "notion" -- node /Users/yourname/mcp-servers/mcp-stagehand-notion.so/dist/index.js
```
### Step 3: Verify Installation
List your configured MCP servers:
```bash theme={null}
claude mcp list
```
You should see your newly added server in the list.
## Using Your MCP Server with Claude
Once configured, you can interact with your MCP server through natural language in Claude Code.
### Example Interactions
```
You: Search Hacker News for articles about AI agents
Claude: I'll search Hacker News for articles about AI agents.
[Uses the search_articles tool from your MCP server]
You: Get the top story from Hacker News right now
Claude: Let me fetch the current top story.
[Uses the get_top_stories tool]
```
```
You: Create a new task in Jira for fixing the login bug
Claude: I'll create a new Jira task for the login bug.
[Uses the create_task tool from your MCP server]
You: Update the status of PROJ-123 to In Progress
Claude: I'll update the task status.
[Uses the update_task_status tool]
```
```
You: Find the latest posts on my Substack about TypeScript
Claude: Let me search your Substack for TypeScript posts.
[Uses the search_posts tool from your MCP server]
You: Get the full content of the most recent post
Claude: I'll fetch the full content.
[Uses the get_post_content tool]
```
## Managing MCP Servers
### List Configured Servers
```bash theme={null}
claude mcp list
```
### Remove a Server
```bash theme={null}
claude mcp remove your-server-name
```
### Update a Server
To update a server after making changes:
1. Rebuild your MCP server:
```bash theme={null}
cd mcp-stagehand-yoursite.com
npm run build
```
2. The changes will be automatically picked up - no need to re-add the server
If you make significant changes to your MCP server, consider removing and re-adding it to ensure a clean configuration.
## Configuration File
Claude Code stores MCP server configurations in:
* **macOS/Linux**: `~/.config/claude/mcp_config.json`
* **Windows**: `%APPDATA%\claude\mcp_config.json`
You can manually edit this file if needed, but using the CLI is recommended.
### Example Configuration
```json theme={null}
{
"mcpServers": {
"hackernews": {
"command": "node",
"args": ["/Users/yourname/mcp-servers/mcp-stagehand-news.ycombinator.com/dist/index.js"],
"transport": "stdio"
},
"notion": {
"command": "node",
"args": ["/Users/yourname/mcp-servers/mcp-stagehand-notion.so/dist/index.js"],
"transport": "stdio"
}
}
}
```
## Best Practices
Keep all your MCP servers in a dedicated directory (e.g., `~/mcp-servers/`) for easier management
Choose clear, descriptive names for your servers that reflect their purpose
Add clear descriptions to your MCP tools so Claude understands when to use them
Use the MCP Inspector to test your servers before integrating with Claude Code
## Troubleshooting
**Solutions:**
* Verify the server is listed with `claude mcp list`
* Restart Claude Code
* Check that the path to `dist/index.js` is correct and absolute
* Ensure the server built successfully (`npm run build`)
**Solutions:**
* Rebuild your MCP server after any changes
* Check server logs for errors
* Test with the MCP Inspector first: `npx @modelcontextprotocol/inspector node dist/index.js`
* Verify your Browserbase API key is valid
**Solutions:**
* Ensure you've created an authentication context: `mcpkit contexts create yoursite.com`
* Verify the context exists: `mcpkit contexts list`
* Try recreating the authentication context if it's expired
**Solutions:**
* Check your Browserbase account for session limits
* Increase timeout values in your MCP server configuration
* Ensure the target website is accessible
* Try reducing the number of concurrent operations
## Next Steps
Generate MCP servers for other websites
Save authentication for sites that require login
See example MCP servers in action
Learn advanced authentication techniques
## Get Help
Get help from the community
Report bugs or request features
# contexts
Source: https://mcpkit.sh/commands/contexts
Manage saved authentication contexts
The `contexts` command helps you manage saved browser authentication contexts. This allows you to reuse login sessions across multiple MCP server generations without having to authenticate every time.
## Usage
```bash theme={null}
mcpkit contexts [domain]
```
### Subcommands
Show all saved authentication contexts
Display details for a specific domain's context
Create a new authentication context for a domain
Remove a saved context for a domain
## Examples
### List All Contexts
View all saved authentication contexts:
```bash theme={null}
mcpkit contexts list
```
Output:
```
Saved Authentication Contexts
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
📦 mcpkit.sh
Created: 2024-01-15 14:30:00
Size: 2.3 KB
📦 github.com
Created: 2024-01-14 10:15:00
Size: 4.1 KB
Total: 2 contexts
```
### Show Context Details
View details for a specific domain:
```bash theme={null}
mcpkit contexts show mcpkit.sh
```
Output:
```
Context: mcpkit.sh
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Domain: mcpkit.sh
Created: 2024-01-15 14:30:00
Last Used: 2024-01-15 16:45:00
Size: 2.3 KB
Cookies: 12
Local Storage Items: 5
Status: ✓ Valid
```
### Create New Context
Create an authentication context for a domain:
```bash theme={null}
mcpkit contexts create mcpkit.sh
```
This will:
1. Launch a live browser session
2. Navigate to the domain
3. Wait for you to complete authentication
4. Save the browser state (cookies, local storage, etc.)
```
🌐 Opening live browser session for mcpkit.sh...
Complete authentication in your browser.
Press Enter when done...
✓ Context saved successfully!
```
Complete all authentication steps including 2FA before pressing Enter.
### Delete Context
Remove a saved authentication context:
```bash theme={null}
mcpkit contexts delete mcpkit.sh
```
Output:
```
✓ Context for mcpkit.sh deleted successfully
```
This action cannot be undone. You'll need to authenticate again to create a
new context.
## How Contexts Work
Authentication contexts store browser state to avoid repeated logins:
When you authenticate during `mcpkit create` or run `mcpkit contexts create`, the browser state is captured including:
* Cookies
* Local storage
* Session storage
* IndexedDB data
The context is saved to your local machine:
```
~/.mcpkit/contexts/
├── mcpkit.sh.json
├── github.com.json
└── notion.com.json
```
Each file contains the serialized browser context.
When creating an MCP server for a domain with a saved context:
```bash theme={null}
mcpkit create https://mcpkit.sh --skip-auth
```
The saved context is loaded, so you don't need to log in again.
Contexts can expire based on the website's session policies. If a context is invalid, you'll be prompted to authenticate again.
## Context Files
### Location
```
~/.mcpkit/contexts/
```
```
%USERPROFILE%\.mcpkit\contexts\
```
### File Format
Context files are JSON containing browser state:
```json theme={null}
{
"domain": "mcpkit.sh",
"created": "2024-01-15T14:30:00.000Z",
"cookies": [
{
"name": "session_token",
"value": "encrypted_value",
"domain": ".mcpkit.sh",
"path": "/",
"expires": 1737820200
}
],
"localStorage": {
"user_id": "user_123",
"theme": "dark"
}
}
```
Context files contain sensitive authentication data. Never share these files
or commit them to version control.
## Use Cases
### Multi-Site Workflow
Save contexts for multiple sites you frequently use:
```bash theme={null}
# Set up contexts once
mcpkit contexts create mcpkit.sh
mcpkit contexts create github.com
mcpkit contexts create notion.com
# Generate servers without re-authenticating
mcpkit create https://mcpkit.sh --skip-auth
mcpkit create https://github.com --skip-auth
mcpkit create https://notion.com --skip-auth
```
### Context Refresh
If your session expires, refresh the context:
```bash theme={null}
# Delete old context
mcpkit contexts delete mcpkit.sh
# Create new context
mcpkit contexts create mcpkit.sh
```
### Team Sharing (Advanced)
For authorized internal tools, you can share contexts (use caution):
```bash theme={null}
# Export context
cp ~/.mcpkit/contexts/internal-tool.com.json ~/shared/
# Team member imports
cp ~/shared/internal-tool.com.json ~/.mcpkit/contexts/
```
Only share contexts for authorized internal tools where you have permission.
Never share personal account contexts.
## Domain Matching
Contexts are matched by domain name:
| URL | Matched Context |
| ---------------------------------- | ------------------------------------------ |
| `https://mcpkit.sh` | `mcpkit.sh` |
| `https://www.mcpkit.sh` | `mcpkit.sh` (or `www.mcpkit.sh` if exists) |
| `https://app.mcpkit.sh` | `mcpkit.sh` (or `app.mcpkit.sh` if exists) |
| `https://mcpkit.sh/team/issue-123` | `mcpkit.sh` |
MCPKit normalizes domains by removing `www.` and subdomains to find the base
domain context.
## Security Considerations
### What's Stored
Contexts contain:
* ✅ Session cookies
* ✅ Authentication tokens
* ✅ Local storage data
* ✅ Session storage data
* ❌ Passwords (never stored)
* ❌ Credit card information
* ❌ Personal messages
### Best Practices
Follow these practices to keep your authentication contexts secure:
1. **Use separate accounts** - Create dedicated accounts for automation when possible
2. **Rotate contexts** - Refresh contexts periodically
3. **Monitor usage** - Check your account activity for unexpected sessions
4. **Delete unused contexts** - Remove contexts you no longer need
5. **Secure your machine** - Use disk encryption and strong passwords
### Permissions
Ensure proper file permissions:
```bash theme={null}
# Check permissions
ls -la ~/.mcpkit/contexts/
# Should be readable only by you (600)
chmod 600 ~/.mcpkit/contexts/*.json
```
## Troubleshooting
If MCPKit can't find a context:
1. **List all contexts:**
```bash theme={null}
mcpkit contexts list
```
2. **Check domain spelling:**
```bash theme={null}
mcpkit contexts show mcpkit.sh
```
3. **Create new context:**
```bash theme={null}
mcpkit contexts create mcpkit.sh
```
If a saved context doesn't work:
1. **Delete and recreate:**
```bash theme={null}
mcpkit contexts delete mcpkit.sh
mcpkit contexts create mcpkit.sh
```
2. **Check website session policies** - Some sites expire sessions quickly
3. **Verify you're still logged in** to the website manually
If context creation fails:
1. **Complete all auth steps** - Including 2FA, email verification, etc.
2. **Wait for full page load** - Don't press Enter until fully logged in
3. **Check browser state** - Make sure cookies are enabled
4. **Try manual authentication:**
* Open the site in a normal browser
* Log in completely
* Then run `mcpkit contexts create`
If deletion fails:
1. **Check file permissions:**
```bash theme={null}
ls -la ~/.mcpkit/contexts/
```
2. **Manually delete:**
```bash theme={null}
rm ~/.mcpkit/contexts/mcpkit.sh.json
```
3. **Verify deletion:**
```bash theme={null}
mcpkit contexts list
```
## Advanced Usage
### Bulk Context Management
List and delete multiple contexts:
```bash theme={null}
# List all contexts
mcpkit contexts list
# Delete old contexts
for domain in old-site1.com old-site2.com; do
mcpkit contexts delete $domain
done
```
### Context Backup
Back up your contexts:
```bash theme={null}
# Create backup directory
mkdir ~/mcpkit-backup
# Copy all contexts
cp ~/.mcpkit/contexts/*.json ~/mcpkit-backup/
# Restore when needed
cp ~/mcpkit-backup/*.json ~/.mcpkit/contexts/
```
### Context Migration
Move contexts to a new machine:
```bash theme={null}
# On old machine
tar -czf mcpkit-contexts.tar.gz -C ~/.mcpkit contexts
# Transfer file to new machine
scp mcpkit-contexts.tar.gz newmachine:~/
# On new machine
mkdir -p ~/.mcpkit
tar -xzf mcpkit-contexts.tar.gz -C ~/.mcpkit
```
## Next Steps
Use saved contexts to generate servers
{" "}
Learn more about authentication handling
{" "}
See example workflows using contexts
Configure your API keys
# create
Source: https://mcpkit.sh/commands/create
Generate MCP servers for any website
The `create` command is the core of MCPKit. It analyzes a website and generates a complete MCP server with tools for interacting with that site.
## Usage
```bash theme={null}
mcpkit create [options]
```
### Arguments
The URL of the website to create an MCP server for. Must be a valid HTTP or
HTTPS URL.
### Options
Skip the authentication step even if the website requires login.
## Examples
### Basic Usage
Create an MCP server for a public website:
```bash theme={null}
mcpkit create https://news.ycombinator.com
```
### With Interactive URL Prompt
If you don't provide a URL, mcpkit will prompt you:
```bash theme={null}
mcpkit create
# ? Enter the URL of the website to create an MCP for: https://mcpkit.sh
```
### Skip Authentication
For testing or public websites:
```bash theme={null}
mcpkit create https://example.com --skip-auth
```
## How It Works
MCPKit validates the provided URL and extracts the domain name.
```
🔨 MCP Server Generator
📍 Analyzing: https://mcpkit.sh
```
A headless browser session is launched via Browserbase to load the website.
The browser runs in the cloud, so you don't need Chrome installed locally.
If the website requires authentication, you'll be prompted to log in:
```
🔐 This site may require authentication.
Would you like to authenticate? (Y/n) y
🌐 Opening live browser session...
Complete authentication in your browser, then press Enter...
```
Your authentication context (cookies, session data) will be saved for future use.
MCPKit uses AI to analyze the page and discover available actions:
```
🔍 Discovering actions...
✅ Found 8 actions:
- Create new issue
- Search issues
- Update issue status
- Add comment
- List projects
- ...
```
The AI examines:
* Interactive elements (buttons, forms, links)
* Page structure and navigation
* Common workflows and patterns
* API endpoints (if available)
For each discovered action, MCPKit generates:
* Tool name and description
* Input parameters with types
* Zod validation schemas
* Implementation code
```typescript theme={null}
// Generated tool example
{
name: "create_issue",
description: "Create a new issue",
inputSchema: {
type: "object",
properties: {
title: { type: "string" },
description: { type: "string" },
priority: {
type: "string",
enum: ["low", "medium", "high", "urgent"]
}
},
required: ["title"]
}
}
```
A complete MCP server project is created:
```
📁 mcp-stagehand-mcpkit.sh/
├── src/
│ ├── index.ts # Main MCP server
│ ├── tools/
│ │ ├── create_issue.ts
│ │ ├── search_issues.ts
│ │ └── ...
│ └── types.ts # Shared types
├── package.json
├── tsconfig.json
└── README.md
```
Your MCP server is ready to use!
## Generated Server Structure
The generated MCP server includes:
### Main Server (`src/index.ts`)
```typescript theme={null}
import { Server } from "@modelcontextprotocol/sdk/server/index.js";
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
const server = new Server(
{
name: "hackernews-mcp-server",
version: "1.0.0",
},
{
capabilities: {
tools: {},
},
}
);
// Tool handlers
server.setRequestHandler(ListToolsRequestSchema, async () => ({
tools: [
// Generated tools
],
}));
server.setRequestHandler(CallToolRequestSchema, async (request) => {
// Tool implementation
});
```
### Tool Implementation
Each tool is implemented with:
```typescript theme={null}
// tools/create_issue.ts
export async function createIssue(params: {
title: string;
description?: string;
priority?: "low" | "medium" | "high" | "urgent";
}) {
const stagehand = await initStagehand();
// Navigate to create issue page
await stagehand.act("click new issue button");
// Fill in form
await stagehand.act(`type "${params.title}" in title field`);
if (params.description) {
await stagehand.act(`type "${params.description}" in description field`);
}
// Submit
await stagehand.act("click create button");
// Extract result
const result = await stagehand.extract("get created issue details");
return result;
}
```
## Configuration
Generated servers can be configured via environment variables:
```bash theme={null}
# .env in generated server directory
BROWSERBASE_API_KEY=your_api_key
BROWSERBASE_PROJECT_ID=your_project_id
LOG_LEVEL=info
```
## Testing the Generated Server
After creation, test your server:
```bash theme={null}
cd mcp-stagehand-/
npm install
npm run build
npx @modelcontextprotocol/inspector node dist/index.js
```
## Advanced Options
### Custom Model for Discovery
The AI model used for action discovery can be configured in your `~/.mcpkit/secrets.json`:
```json theme={null}
{
"llmProvider": "google",
"llmApiKey": "your-api-key",
"llmModel": "gemini-2.0-flash-exp"
}
```
Supported providers:
* `google` - Gemini models (recommended)
* `openai` - GPT models
* `anthropic` - Claude models
* `azure` - Azure OpenAI
### Debugging
For verbose output during generation:
```bash theme={null}
DEBUG=mcpkit:* mcpkit create https://example.com
```
## Common Workflows
For websites that don't require authentication:
```bash theme={null}
# Create server
mcpkit create https://news.ycombinator.com
# Test it
cd mcp-stagehand-news.ycombinator.com
npm install && npm run build
npx @modelcontextprotocol/inspector node dist/index.js
```
For websites requiring login:
```bash theme={null}
# Create server with auth
mcpkit create https://mcpkit.sh
# Follow prompts to authenticate
# Context is saved, regenerate without auth:
mcpkit create https://mcpkit.sh --skip-auth
```
For company internal tools:
```bash theme={null}
# Make sure you can access the tool
mcpkit create https://internal.company.com
# You may need VPN or network access
```
Ensure you have permission to automate interactions with internal tools.
## Troubleshooting
If MCPKit doesn't find any actions:
1. **Try a more specific URL** - Navigate to a specific page with clear actions
```bash theme={null}
# Instead of homepage
mcpkit create https://mcpkit.sh/issues
```
2. **Authenticate first** - Some content only appears after login
```bash theme={null}
mcpkit create https://example.com
# Choose Yes when prompted to authenticate
```
3. **Check the website is accessible** - Make sure it's not behind a firewall or paywall
If authentication doesn't work:
1. **Complete the full login flow** - Don't close the browser until you see success
2. **Check for 2FA** - Some sites require two-factor authentication
3. **Verify credentials** - Make sure you're using valid credentials
4. **Try manual context creation**:
```bash theme={null}
mcpkit contexts create example.com
```
If the generated tools don't work correctly:
1. **Check Browserbase API key** in the generated `.env` file
2. **Verify authentication** - Make sure saved context is still valid
3. **Test individual actions** in the MCP Inspector
4. **Regenerate with updated context**:
```bash theme={null}
mcpkit contexts delete example.com
mcpkit create https://example.com
```
## Next Steps
Learn how to manage authentication contexts
{" "}
Update your API keys and settings
{" "}
See example generated servers
# secrets
Source: https://mcpkit.sh/commands/secrets
Manage API keys and configuration
The `secrets` command helps you set up and manage API keys required for MCPKit to function.
## Usage
```bash theme={null}
mcpkit secrets [subcommand]
```
### Subcommands
Run the interactive setup wizard to configure or update your API keys.
Display your current configuration (without revealing full API keys).
## Examples
### Initial Setup
Run the interactive setup wizard:
```bash theme={null}
mcpkit secrets
```
You'll be prompted for:
1. **Browserbase API Key**
```
? Enter your Browserbase API key: bb_xxxxxxxxxxxxxxxx
```
2. **LLM Provider**
```
? Select your LLM provider:
❯ Google Gemini (recommended)
OpenAI
Anthropic
Azure OpenAI
```
3. **LLM API Key**
```
? Enter your Gemini API key: AIxxxxxxxxxxxxxxxxx
```
Your secrets are now configured and saved to `~/.mcpkit/secrets.json`
### View Current Configuration
Check what's currently configured:
```bash theme={null}
mcpkit secrets show
```
Output:
```
Current Configuration:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
LLM Provider: google
LLM Model: gemini-2.0-flash-exp
Browserbase API: Configured ✓
LLM API Key: Configured ✓
```
## Configuration Details
### Storage Location
Your secrets are stored in a JSON file at:
```
~/.mcpkit/secrets.json
```
```
%USERPROFILE%\.mcpkit\secrets.json
```
Never commit `secrets.json` to version control. This file contains sensitive
API keys.
### File Format
The secrets file has this structure:
```json theme={null}
{
"browserbaseApiKey": "bb_xxxxxxxxxxxxxxxx",
"llmProvider": "google",
"llmApiKey": "AIxxxxxxxxxxxxxxxxx",
"llmModel": "gemini-2.0-flash-exp"
}
```
## Supported LLM Providers
MCPKit supports multiple LLM providers for AI-powered action discovery:
### Google Gemini (Recommended)
Best balance of speed, quality, and cost. Free tier available.
**Get an API key:** [Google AI Studio](https://aistudio.google.com/app/apikey)
**Supported models:**
* `gemini-2.0-flash-exp` (recommended)
* `gemini-1.5-pro`
* `gemini-1.5-flash`
**Configuration:**
```json theme={null}
{
"llmProvider": "google",
"llmApiKey": "AIxxxxxxxxxxxxxxxxx",
"llmModel": "gemini-2.0-flash-exp"
}
```
### OpenAI
High quality but more expensive. Good for complex websites.
**Get an API key:** [OpenAI Platform](https://platform.openai.com)
**Supported models:**
* `gpt-4o`
* `gpt-4o-mini`
* `gpt-4-turbo`
**Configuration:**
```json theme={null}
{
"llmProvider": "openai",
"llmApiKey": "sk-xxxxxxxxxxxxxxxx",
"llmModel": "gpt-4o"
}
```
### Anthropic
Excellent reasoning capabilities for complex page analysis.
**Get an API key:** [Anthropic Console](https://console.anthropic.com)
**Supported models:**
* `claude-3-5-sonnet-20241022`
* `claude-3-opus-20240229`
**Configuration:**
```json theme={null}
{
"llmProvider": "anthropic",
"llmApiKey": "sk-ant-xxxxxxxxxxxxxxxx",
"llmModel": "claude-3-5-sonnet-20241022"
}
```
### Azure OpenAI
Enterprise option with compliance and data residency.
**Configuration:**
```json theme={null}
{
"llmProvider": "azure",
"azureApiKey": "xxxxxxxxxxxxxxxx",
"azureEndpoint": "https://your-resource.openai.azure.com",
"azureDeployment": "gpt-4o",
"llmModel": "gpt-4o"
}
```
## Browserbase Configuration
MCPKit uses [Stagehand](https://docs.stagehand.dev/) and [Browserbase](https://www.browserbase.com) for serverless browser automation.
### Get a Browserbase API Key
Create a free account at [browserbase.com](https://www.browserbase.com)
Go to your dashboard and click on Settings
Find your API key in the API Keys section
Run `mcpkit secrets` and paste your API key when prompted
### Browserbase Pricing
* **Free tier**: 100 hours/month of browser time
* Perfect for development and testing
* Upgrade for production use
## Updating Secrets
To update your configuration, simply run the setup wizard again:
```bash theme={null}
mcpkit secrets
```
Your existing values will be shown as defaults. Press Enter to keep them, or type new values to update.
## Manual Configuration
You can also manually edit the secrets file:
```bash theme={null}
# Edit with your preferred editor
nano ~/.mcpkit/secrets.json
# Or use vim
vim ~/.mcpkit/secrets.json
```
```powershell theme={null}
# Edit with notepad
notepad "$env:USERPROFILE\.mcpkit\secrets.json"
```
Make sure the JSON is valid after manual edits, or MCPKit may fail to read the
configuration.
## Environment Variables
You can also configure secrets via environment variables (useful for CI/CD):
```bash theme={null}
export BROWSERBASE_API_KEY="bb_xxxxxxxxxxxxxxxx"
export LLM_PROVIDER="google"
export LLM_API_KEY="AIxxxxxxxxxxxxxxxxx"
export LLM_MODEL="gemini-2.0-flash-exp"
mcpkit create https://example.com
```
Environment variables take precedence over the secrets file.
## Troubleshooting
If you get "Invalid API key" errors:
1. **Verify the key** - Make sure you copied it correctly
2. **Check provider** - Ensure you're using the right provider
3. **Test the key** directly with the provider's API
4. **Regenerate** - Create a new API key if needed
If MCPKit can't find your secrets:
1. **Run setup again:**
```bash theme={null}
mcpkit secrets
```
2. **Check file permissions:**
```bash theme={null}
ls -la ~/.mcpkit/
```
3. **Create directory manually:**
```bash theme={null}
mkdir -p ~/.mcpkit
mcpkit secrets
```
If you hit rate limits:
1. **Check your usage** on the provider's dashboard
2. **Upgrade your plan** if needed
3. **Switch providers** temporarily:
```bash theme={null}
mcpkit secrets
# Select a different provider
```
If your secrets file is corrupted:
1. **Backup the file:**
```bash theme={null}
cp ~/.mcpkit/secrets.json ~/.mcpkit/secrets.json.bak
```
2. **Delete and recreate:**
```bash theme={null}
rm ~/.mcpkit/secrets.json
mcpkit secrets
```
3. **Validate JSON:**
```bash theme={null}
cat ~/.mcpkit/secrets.json | python -m json.tool
```
## Security Best Practices
Your API keys provide access to paid services. Follow these practices to keep
them secure:
* ✅ Never commit secrets files to git
* ✅ Use environment variables in CI/CD
* ✅ Rotate keys regularly
* ✅ Use separate keys for development and production
* ✅ Set spending limits on provider dashboards
* ❌ Don't share secrets files
* ❌ Don't expose keys in logs or screenshots
* ❌ Don't use production keys in public repositories
## Next Steps
Use your configured secrets to create an MCP server
Learn about authentication contexts
# Development
Source: https://mcpkit.sh/development
Contributing to MCPKit and developing locally
This guide covers how to set up MCPKit for local development and contribute to the project.
## Development Setup
```bash theme={null}
git clone https://github.com/kevoconnell/mcpkit.git
cd mcpkit
```
{" "}
`bash npm install `
{" "}
`bash npm run build `
```bash theme={null}
npm link
```
Now you can use `mcpkit` command globally with your local changes.
## Running Locally
Test your changes without building:
```bash theme={null}
# Use tsx for hot reload
npm run dev create https://example.com
# Or run commands directly
npx tsx src/cli.ts create https://example.com
npx tsx src/cli.ts secrets
npx tsx src/cli.ts contexts list
```
## Contributing
### Pull Request Process
1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Make your changes
4. Test thoroughly with multiple websites
5. Commit (`git commit -m 'feat: add amazing feature'`)
6. Push (`git push origin feature/amazing-feature`)
7. Open a Pull Request
### Commit Convention
Use conventional commits:
* `feat:` - New feature
* `fix:` - Bug fix
* `docs:` - Documentation changes
* `chore:` - Maintenance tasks
## Getting Help
Ask questions and discuss ideas
Chat with contributors
# Hacker News Example
Source: https://mcpkit.sh/examples/hackernews
Build an MCP server for Hacker News using MCPKit
This example shows how to create an MCP server for [Hacker News](https://news.ycombinator.com), a popular tech news aggregator. This is a great first example because it doesn't require authentication.
## What You'll Build
An MCP server that enables AI assistants to:
* View articles from the homepage
* Read comments on posts
* Navigate different sections (new, best, ask, show)
* Search for posts
* Submit new posts
* View user profiles
## Generate the Server
Create the MCP server with a single command:
```bash theme={null}
mcpkit create https://news.ycombinator.com
```
MCPKit analyzes the Hacker News homepage and discovers available actions.
```
🔨 MCP Server Generator
📍 Analyzing: https://news.ycombinator.com
```
The AI discovers 6 main actions:
```
🔍 Discovering actions...
✅ Found 6 actions:
- view_article
- view_comments
- navigate_section
- search_posts
- submit_post
- view_user_profile
```
A complete MCP server is generated:
```
📁 mcp-stagehand-news.ycombinator.com/
├── src/
│ └── index.ts
├── package.json
└── tsconfig.json
```
Your Hacker News MCP server is ready!
## Available Tools
The generated server includes these tools:
### 1. view\_article
View a specific article from the homepage.
**Parameters:**
The title of the article to view
**Example usage:**
```
User: Show me the top article on Hacker News
AI: [Uses view_article with the title of the top article]
```
### 2. view\_comments
View the comments for a specific article.
**Parameters:**
The title of the article whose comments to view
**Example usage:**
```
User: Show me the comments on the article about AI safety
AI: [Uses view_comments with title "AI safety discussion"]
```
### 3. navigate\_section
Navigate to different sections of Hacker News.
**Parameters:**
The section to navigate to (e.g., "new", "best", "ask", "show", "jobs")
**Example usage:**
```
User: What are the newest posts on HN?
AI: [Uses navigate_section with section "new"]
```
### 4. search\_posts
Search Hacker News for posts matching a query.
**Parameters:**
The search query
**Example usage:**
```
User: Search Hacker News for articles about React
AI: [Uses search_posts with query "React"]
```
### 5. submit\_post
Submit a new post to Hacker News (requires authentication).
**Parameters:**
The title of the post
The URL of the post (optional)
The text content (optional, if no URL)
This tool requires authentication. You'll need to create an authenticated context first.
### 6. view\_user\_profile
View the profile of a specific Hacker News user.
**Parameters:**
The username of the profile to view
**Example usage:**
```
User: Show me pg's profile on Hacker News
AI: [Uses view_user_profile with username "pg"]
```
## Setup and Testing
### Build the Server
```bash theme={null}
cd mcp-stagehand-news.ycombinator.com
npm install
npm run build
```
### Test with MCP Inspector
```bash theme={null}
npx @modelcontextprotocol/inspector node dist/index.js
```
This opens a web interface where you can test each tool:
### Add to Claude Code
```bash theme={null}
claude mcp add --transport stdio "hackernews" -- node /absolute/path/to/dist/index.js
```
## Example Prompts
Once your server is connected, try these prompts:
**Prompt:** "Search Hacker News for articles about LLMs from the past week"
**What happens:**
1. Uses `search_posts` with query "LLMs"
2. Filters results by date
3. Returns summaries of relevant articles
**Prompt:** "What are the top 3 posts on Hacker News right now and what are people saying about them?"
**What happens:**
1. Navigates to homepage
2. Extracts top 3 article titles
3. Uses `view_comments` for each
4. Summarizes discussion themes
**Prompt:** "Show me what patio11 has been posting about lately"
**What happens:**
1. Uses `view_user_profile` with username "patio11"
2. Extracts recent submissions and comments
3. Summarizes activity
**Prompt:** "Find Ask HN posts about career advice"
**What happens:**
1. Uses `navigate_section` with "ask"
2. Uses `search_posts` with "career advice"
3. Returns relevant discussions
## How It Works
### Under the Hood
The generated tools use Stagehand's AI-powered browser automation:
```typescript theme={null}
// Example: view_article tool implementation
async function viewArticle(title: string) {
const stagehand = await initStagehand();
const page = stagehand.context.pages()[0];
await page.goto(TARGET_URL);
// Use Stagehand's act method to click the article
await stagehand.act(`click on the article titled "${title}"`);
// Extract article content
const content = await stagehand.extract(
"extract article title, URL, and text content",
z.object({
title: z.string(),
url: z.string().url(),
content: z.string()
})
);
return content;
}
```
### Context Management
The server automatically manages Browserbase contexts:
1. **Check for saved context** - Looks for `~/.mcpkit/contexts/news.ycombinator.com.txt`
2. **Create new if needed** - Creates a fresh Browserbase context
3. **Initialize Stagehand** - Connects to the browser session
4. **Execute action** - Runs the requested tool
5. **Return results** - Sends structured data back to the AI
## Customization Ideas
### Add More Tools
Extend the generated server with custom tools:
```typescript theme={null}
// Add a tool to get top comments
{
name: "get_top_comments",
description: "Get the most upvoted comments on an article",
inputSchema: {
type: "object",
properties: {
title: { type: "string" },
limit: { type: "number", default: 5 }
}
}
}
```
### Improve Extraction
Enhance data extraction with better schemas:
```typescript theme={null}
const ArticleSchema = z.object({
title: z.string(),
url: z.string().url(),
points: z.number(),
author: z.string(),
timestamp: z.string(),
commentCount: z.number(),
content: z.string().optional()
});
```
### Add Caching
Cache frequently accessed data:
```typescript theme={null}
const articleCache = new Map();
async function viewArticle(title: string) {
if (articleCache.has(title)) {
return articleCache.get(title);
}
const result = await fetchArticle(title);
articleCache.set(title, result);
return result;
}
```
## Common Use Cases
Use the Hacker News MCP to research technical topics:
```
"Find discussions about Rust vs Go on Hacker News and summarize the main arguments"
```
The AI will:
* Search for relevant posts
* Read comment threads
* Extract key points from discussions
* Provide a balanced summary
Monitor what's trending in tech:
```
"What are the hottest topics on HN today?"
```
The AI will:
* Check top posts
* Analyze comment engagement
* Identify recurring themes
* Report trending topics
Find content for newsletters or social media:
```
"Find the most interesting AI-related posts from this week with active discussions"
```
The AI will:
* Search for AI posts
* Filter by date and activity
* Read comments to gauge interest
* Curate a list of top posts
## Troubleshooting
Hacker News is usually fast, but if tools timeout:
1. **Check internet connection**
2. **Verify Browserbase quota** - Make sure you haven't hit limits
3. **Try again** - HN can occasionally be slow
If `view_article` can't find an article:
1. **Check exact title** - Use the exact title from HN
2. **Article may have fallen off front page** - Try navigating to "new" first
3. **Use search instead** - Try `search_posts` for more flexibility
To submit posts, you need authentication:
```bash theme={null}
# Create authenticated context
mcpkit contexts create news.ycombinator.com
# Regenerate server with context
mcpkit create https://news.ycombinator.com --skip-auth
```
## Next Steps
See other example MCP servers
Learn to extend generated servers
Add authenticated features
Integrate with your AI assistant
# Overview
Source: https://mcpkit.sh/examples/overview
Real-world examples of MCP servers generated with MCPKit
This section contains examples of MCP servers generated with MCPKit for different types of websites and use cases.
## Example Categories
Hacker News - News aggregation and discussions
{" "}
Reddit, Twitter/X - Social platforms
Shopping sites and marketplaces
## What You'll Learn
Each example includes:
* **Setup instructions** - How to generate the MCP server
* **Authentication guide** - Handling login if required
* **Available tools** - What the AI can do with the site
* **Usage examples** - Real prompts and expected results
* **Customization tips** - How to extend the generated server
## Quick Examples
### 1. Hacker News (No Auth Required)
Generate an MCP server for browsing and searching Hacker News:
```bash theme={null}
mcpkit create https://news.ycombinator.com
```
**What you can do:**
* Search for articles about specific topics
* Get top stories
* Read article comments
* Find trending discussions
**Example usage:**
```
User: Search Hacker News for articles about AI safety
AI: [Uses search_articles tool with query "AI safety"]
```
### 2. Substack (Content Platform)
Generate an MCP server for the Substack newsletter platform:
```bash theme={null}
mcpkit create https://substack.com
```
**What you can do:**
* Search for publications by topic
* Read newsletter posts
* Browse trending content
* View author profiles
**Example usage:**
```
User: Find tech newsletters about AI and show me their latest posts
AI: [Uses search_publications and read_post tools]
```
### 3. GitHub (Public + Private)
Generate an MCP server for GitHub:
```bash theme={null}
mcpkit create https://github.com
```
**What you can do:**
* Search repositories
* View issues and pull requests
* Read file contents
* Check commit history
**Example usage:**
```
User: Find React repositories with over 10k stars
AI: [Uses search_repositories tool with filters]
```
## Example Workflows
### Research & Monitoring
Use multiple MCP servers together to gather information:
```bash theme={null}
# Set up servers for different sources
mcpkit create https://news.ycombinator.com
mcpkit create https://github.com
mcpkit create https://reddit.com
# Then ask Claude to:
# "Search HN, GitHub, and Reddit for discussions about NextJS 14"
```
### Project Management Automation
Automate your workflow across tools:
```bash theme={null}
# Set up authenticated sites
mcpkit contexts create mcpkit.sh
mcpkit contexts create github.com
mcpkit create https://mcpkit.sh --skip-auth
mcpkit create https://github.com --skip-auth
# Then ask Claude to automate workflows across platforms
```
### Content Curation
Gather and organize content from multiple sources:
```bash theme={null}
mcpkit create https://news.ycombinator.com
mcpkit create https://medium.com
mcpkit create https://dev.to
# Then ask Claude to:
# "Find the top 5 articles about React Hooks from HN, Medium, and DEV"
```
## Featured Examples
**Type:** Public + Authenticated (for premium content)
**Use Case:** Content discovery, newsletter aggregation, research
**Key Features:**
* Search publications by topic
* Read posts and articles
* Browse trending content
* View author profiles
**Authentication:** Optional (required for subscriber-only content)
[View Full Example →](/examples/substack)
**Type:** Public, No Auth
**Use Case:** News discovery, trend monitoring, research
**Key Features:**
* Search articles by keyword
* Get top stories
* Read comments and discussions
* Filter by date and score
**Authentication:** Not required
[View Full Example →](/examples/hackernews)
**Type:** Enterprise, Authenticated
**Use Case:** Knowledge base search, documentation
**Key Features:**
* Search documentation
* Read page contents
* Navigate page hierarchy
* Extract structured data
**Authentication:** Required (SSO, credentials)
**Note:** For internal tools, ensure you have authorization to automate access.
**Type:** Public/Authenticated
**Use Case:** Product research, price monitoring, inventory checking
**Key Features:**
* Search products
* Get product details
* Check availability
* Compare prices
**Authentication:** Optional (for account features)
## Best Practices from Examples
### 1. Start Simple
Begin with public websites that don't require authentication:
```bash theme={null}
# Good first examples
mcpkit create https://news.ycombinator.com
mcpkit create https://producthunt.com
mcpkit create https://reddit.com
```
### 2. Save Authentication Contexts
For sites you use frequently, save contexts:
```bash theme={null}
# Authenticate once
mcpkit create https://mcpkit.sh
# Reuse later
mcpkit create https://mcpkit.sh --skip-auth
```
### 3. Test Individual Tools
Use the MCP Inspector to test tools before using in production:
```bash theme={null}
cd mcp-stagehand-example.com
npx @modelcontextprotocol/inspector node dist/index.js
```
### 4. Combine Multiple Servers
Use multiple MCP servers together for powerful workflows:
* Research: HN + Reddit + Substack
* Development: GitHub + Stack Overflow + Dev.to
* Content: Medium + Substack + Hashnode
## Tips for Success
Learn from successful MCPKit users:
1. **Be specific with URLs** - Use the exact page where actions happen
```bash theme={null}
# Instead of homepage
mcpkit create https://mcpkit.sh/team/issues
```
2. **Complete authentication fully** - Including 2FA before continuing
3. **Test in Inspector first** - Validate tools before production use
4. **Handle rate limits** - Add delays between rapid requests
5. **Keep contexts fresh** - Refresh authentication periodically
## Need Help?
Each example includes troubleshooting tips. If you run into issues:
Ask the community for help
Share your examples and get feedback
## Next Steps
Build a Hacker News MCP
Build a Substack MCP
Learn to customize generated servers
Deep dive into auth handling
# Substack Example
Source: https://mcpkit.sh/examples/substack
Build an MCP server for Substack newsletter platforms
This example shows how to create an MCP server for [Substack](https://substack.com), a popular newsletter and publishing platform. This demonstrates how to work with content platforms and manage subscriptions.
## What You'll Build
An MCP server that enables AI assistants to:
* Browse and search Substack publications
* Read newsletter posts and articles
* Navigate author profiles
* Discover trending publications
* Search content across Substack
## Generate the Server
Create the MCP server for Substack:
```bash theme={null}
mcpkit create https://substack.com
```
For a specific Substack publication, you can use the publication's URL instead (e.g., `https://example.substack.com`)
MCPKit analyzes Substack and discovers browsing capabilities.
```
🔨 MCP Server Generator
📍 Analyzing: https://substack.com
🚀 Starting browser session...
```
The AI discovers actions for browsing and reading content:
```
🔍 Discovering actions...
✅ Found 8 actions:
- search_publications
- view_publication
- read_post
- view_author_profile
- browse_categories
- get_trending
- search_posts
- view_post_comments
```
Your MCP server is generated:
```
📁 mcp-stagehand-substack.com/
├── src/
│ └── index.ts
├── package.json
└── tsconfig.json
```
## Available Tools
The generated server typically includes:
### Content Discovery
Search for Substack publications by topic or name.
**Parameters:**
Search query (e.g., "tech", "politics", "cooking")
**Example usage:**
```
User: Find Substack newsletters about AI and machine learning
AI: [Uses search_publications with query "AI machine learning"]
```
**Returns:** List of publications with titles, descriptions, and URLs
Browse Substack publications by category.
**Parameters:**
Category name (e.g., "Technology", "Culture", "Politics")
**Example:**
```typescript theme={null}
{
"category": "Technology"
}
```
Get currently trending publications and posts on Substack.
**Parameters:** None required
**Example usage:**
```
User: What are the trending newsletters on Substack right now?
AI: [Uses get_trending to fetch current trends]
```
### Reading Content
View details and recent posts from a specific publication.
**Parameters:**
URL of the Substack publication
**Example:**
```typescript theme={null}
{
"publicationUrl": "https://stratechery.com"
}
```
**Returns:** Publication details, recent posts, subscriber count
Read the full content of a specific post.
**Parameters:**
URL of the post to read
**Example usage:**
```
User: Read the latest post from Platformer
AI: [Uses view_publication to get latest post URL, then read_post]
```
**Returns:** Post title, author, date, full content, and images
View comments and discussions on a post.
**Parameters:**
URL of the post
**Returns:** Comments with author names and timestamps
Search for specific posts across Substack.
**Parameters:**
Search query
Filter by specific author (optional)
**Example:**
```typescript theme={null}
{
"query": "GPT-4",
"author": "Casey Newton"
}
```
View an author's profile and their publications.
**Parameters:**
Author's name or profile URL
**Returns:** Bio, publications, social links
## Setup and Testing
### Build the Server
```bash theme={null}
cd mcp-stagehand-substack.com
npm install
npm run build
```
### Test with MCP Inspector
```bash theme={null}
npx @modelcontextprotocol/inspector node dist/index.js
```
### Add to Claude Code
```bash theme={null}
claude mcp add --transport stdio "substack" -- node /absolute/path/to/dist/index.js
```
## Example Use Cases
**Prompt:** "Find the top 5 tech newsletters on Substack and summarize their latest posts"
**What happens:**
1. Uses `search_publications` with query "technology"
2. For top 5 results, uses `view_publication`
3. For each publication, uses `read_post` for latest post
4. Summarizes findings
**Prompt:** "Search Substack for articles about climate change from the past month"
**What happens:**
1. Uses `search_posts` with query "climate change"
2. Filters results by date
3. Reads relevant posts
4. Provides summary with sources
**Prompt:** "Show me what Casey Newton has been writing about lately"
**What happens:**
1. Uses `view_author_profile` for "Casey Newton"
2. Gets their publications
3. Uses `view_publication` to see recent posts
4. Summarizes recent topics
**Prompt:** "What topics are trending on Substack this week?"
**What happens:**
1. Uses `get_trending` to see popular posts
2. Analyzes titles and topics
3. Groups by theme
4. Reports trending topics with examples
## Authentication (Optional)
For full access including subscriber-only content:
```bash theme={null}
# Authenticate to access premium content
mcpkit contexts create substack.com
```
**Benefits of authentication:**
* Read subscriber-only posts
* Access full comment threads
* View analytics (for your publications)
* Manage your subscriptions
## Customization Ideas
### Add Newsletter Digest
```typescript theme={null}
{
name: "create_weekly_digest",
description: "Create a weekly digest from favorite publications",
inputSchema: {
type: "object",
properties: {
publications: {
type: "array",
items: { type: "string" },
description: "List of publication URLs"
}
}
}
}
```
### Track Specific Topics
```typescript theme={null}
{
name: "track_topic",
description: "Monitor Substack for posts about a specific topic",
inputSchema: {
type: "object",
properties: {
topic: { type: "string" },
frequency: {
type: "string",
enum: ["daily", "weekly"]
}
}
}
}
```
### Export to Markdown
```typescript theme={null}
// Add to read_post implementation
const markdown = `# ${post.title}
By ${post.author} on ${post.date}
${post.content}
---
Source: ${post.url}
`;
// Save or return markdown
await fs.writeFile(`posts/${post.slug}.md`, markdown);
```
## Common Workflows
### Newsletter Aggregation
Combine multiple newsletters into a single feed:
```
"Create a summary of this week's posts from my favorite tech newsletters:
Stratechery, Platformer, and The Generalist"
```
### Content Research
Research a topic across multiple publications:
```
"Search all Substack posts about Web3 from the past 3 months and
identify the main themes and controversies"
```
### Author Tracking
Follow specific authors across their publications:
```
"Track all posts from Ben Thompson and create a monthly summary
of his analysis on Big Tech companies"
```
## Troubleshooting
Some content is subscriber-only. To access:
1. **Authenticate:**
```bash theme={null}
mcpkit contexts create substack.com
```
2. **Subscribe** to publications you want to read
3. **Regenerate** the server with authentication
If search returns limited results:
1. **Use broader queries** - Try general terms first
2. **Search specific publications** - Use `view_publication` then search within
3. **Try author names** - Search by author for better targeting
Substack pages can be content-heavy:
1. **Be patient** - Allow time for page loads
2. **Use specific URLs** - Direct links are faster than searching
3. **Cache results** - Store frequently accessed content
## Best Practices
Tips for effective automation with Substack:
1. **Respect Rate Limits** - Don't make rapid-fire requests
2. **Cache Content** - Store posts you've already read
3. **Use Specific URLs** - Direct links are more reliable than searches
4. **Attribute Sources** - Always credit authors and link to originals
5. **Subscribe to Support** - If you regularly read a publication, subscribe
## Advanced Features
### Content Analysis
```typescript theme={null}
case "analyze_publication_style": {
// Read multiple posts
const posts = await getRecentPosts(publicationUrl);
// Extract text
const content = posts.map(p => p.content).join("\n\n");
// Analyze with AI
const analysis = await analyzeWritingStyle(content);
return {
content: [{
type: "text",
text: JSON.stringify(analysis, null, 2)
}]
};
}
```
### Recommendation Engine
```typescript theme={null}
case "get_recommendations": {
const { interests } = args as { interests: string[] };
// Search for publications matching interests
const results = await Promise.all(
interests.map(interest =>
searchPublications(interest)
)
);
// Rank and dedupe
const recommendations = rankPublications(results.flat());
return {
content: [{
type: "text",
text: JSON.stringify(recommendations, null, 2)
}]
};
}
```
## Next Steps
Build a news aggregation MCP
Extend your Substack server
Browse more examples
Set up authenticated access
## Real-World Applications
Create a daily digest from your favorite newsletters:
* Aggregate posts from multiple publications
* Summarize key points
* Filter by topics of interest
* Deliver via email or Slack
Research topics across Substack:
* Search for specific themes
* Track emerging trends
* Identify key voices
* Export findings to notes
Analyze successful Substack content:
* Study popular writers' styles
* Identify trending topics
* Research similar publications
* Generate content ideas
# Introduction
Source: https://mcpkit.sh/index
Generate MCP servers for any website with AI-powered browser automation
## What is MCPKit?
**MCPKit** is a CLI tool that generates [Model Context Protocol (MCP)](https://modelcontextprotocol.io) servers for any website using [Stagehand](https://github.com/browserbase/stagehand). With MCPKit, you can give any AI assistant the ability to interact with websites through natural language.
Automatically create MCP servers by analyzing any website's functionality
Automatically detect and document website actions using AI
Save and reuse authentication contexts across sessions
## Quick Start
Get up and running in minutes:
```bash theme={null}
npm install -g @kevinoconnell/mcpkit
```
```bash theme={null}
mcpkit secrets
```
You'll need:
* Browserbase API key and Project ID ([get here!](https://www.browserbase.com))
* LLM API key (Gemini, OpenAI, etc.)
* LLM provider model name (ex: google/gemini-2.5-pro)
```bash theme={null}
mcpkit create https://mcpkit.sh
```
Follow our detailed quickstart guide to create your first MCP server
## How It Works
MCPKit uses AI to:
1. **Analyze** - Navigate to your target website and discover available actions
2. **Authenticate** - Optionally save authentication contexts for future use
3. **Generate** - Create a complete MCP server with tools based on discovered actions
4. **Deploy** - Use your MCP server with Claude Code, Cursor, or any MCP client
## Use Cases
Generate MCP servers for Jira, Asana, ClickUp, or other project management tools to let AI assistants create tasks, update issues, and manage projects.
{" "}
Create servers for content sites like Hacker News, Reddit, or Medium to enable
AI-powered content discovery and interaction.
{" "}
Build MCP servers for your company's internal web applications to automate
workflows and improve productivity.
Generate servers for data sources, dashboards, or monitoring tools to help AI assistants gather and analyze information.
## Key Features
### AI-Powered Action Discovery
MCPKit automatically discovers what actions are possible on a website by:
* Analyzing page structure and interactive elements
* Understanding navigation patterns
* Identifying common workflows
* Generating tool schemas for each action
### Authentication Management
Save authentication contexts to avoid repeated logins:
```bash theme={null}
# List saved contexts
mcpkit contexts list
# Create a new authenticated context
mcpkit contexts create mcpkit.sh
# Delete a context
mcpkit contexts delete mcpkit.sh
```
### Flexible MCP Servers
Generated servers include:
* Complete MCP tool definitions
* Type-safe schemas with Zod validation
* Authentication handling
* Error management
* Logging and debugging support
## What You Can Build
With MCPKit generated MCP servers, you can:
* ✅ Create and update tasks in project management tools
* ✅ Search and extract data from websites
* ✅ Automate form submissions and workflows
* ✅ Monitor dashboards and gather analytics
* ✅ Interact with internal company tools
* ✅ Build custom AI agents with web access
## Technology Stack
MCPKit is built on:
* **[Stagehand](https://www.stagehand.dev)** - AI-powered browser automation
* **[Browserbase](https://www.browserbase.com)** - Serverless browser infrastructure
* **[Model Context Protocol](https://modelcontextprotocol.io)** - Standard for AI-tool communication
* **TypeScript** - Type-safe code generation
## Next Steps
Create your first MCP server in minutes
{" "}
Learn about all available commands
{" "}
See example MCP servers
Integrate with your AI coding assistant
# Installation
Source: https://mcpkit.sh/installation
Install and configure MCPKit on your system
## System Requirements
Before installing MCPKit, ensure your system meets these requirements:
* **Node.js** 18.0.0 or later
* **npm** 9.0.0 or later (comes with Node.js)
* **Operating System**: macOS, Linux, or Windows
Check your Node.js version with `node --version`
## Install with npm
The easiest way to install MCPKit is via npm:
```bash theme={null}
npm install -g @kevinoconnell/mcpkit
```
The `-g` flag installs MCPKit globally, making it available from anywhere in your terminal.
### Verify Installation
Confirm MCPKit is installed correctly:
```bash theme={null}
mcpkit version
```
You should see the current version number printed to the console.
## Alternative Installation Methods
```bash theme={null}
pnpm add -g @kevinoconnell/mcpkit
```
```bash theme={null}
yarn global add @kevinoconnell/mcpkit
```
Clone and build from the GitHub repository:
```bash theme={null}
git clone https://github.com/kevoconnell/mcpkit.git
cd mcpkit
npm install
npm run build
npm link
```
Building from source is useful for development or if you want to use the latest unreleased features.
## Initial Configuration
After installing MCPKit, you need to configure your API keys.
### Get Your API Keys
You'll need:
1. **Browserbase API Key and Project id**
* Sign up at [browserbase.com](https://www.browserbase.com)
* Navigate to your dashboard
* Copy your API key and Project ID from the settings
2. **LLM API Key** (choose one):
* **Google Gemini** (recommended): Get an API key from [Google AI Studio](https://aistudio.google.com/app/apikey)
* **OpenAI**: Get an API key from [OpenAI Platform](https://platform.openai.com)
* **Anthropic**: Get an API key from [Anthropic Console](https://console.anthropic.com)
### Configure Secrets
Run the setup wizard:
```bash theme={null}
mcpkit secrets
```
You'll be prompted to enter your credentials:
```
? Enter your Browserbase API key: bb_xxxxxxxxxxxxxxxx
? Select your LLM provider: Google Gemini
? Enter your Gemini API key: AIxxxxxxxxxxxxxxxxx
```
Your credentials are stored locally in `~/.mcpkit/secrets.json` and are never shared.
### Verify Configuration
Check that your secrets are configured correctly:
```bash theme={null}
mcpkit secrets show
```
This will display your configured provider (without showing the full API keys).
## Updating MCPKit
To update to the latest version:
```bash theme={null}
npm update -g @kevinoconnell/mcpkit
```
Or reinstall:
```bash theme={null}
npm install -g @kevinoconnell/mcpkit@latest
```
Check for updates regularly to get the latest features and bug fixes.
## Uninstalling
To remove MCPKit from your system:
```bash theme={null}
npm uninstall -g @kevinoconnell/mcpkit
```
Your configuration files in `~/.mcpkit/` will remain. To completely remove all MCPKit data:
```bash theme={null}
npm uninstall -g @kevinoconnell/mcpkit
rm -rf ~/.mcpkit
```
```powershell theme={null}
npm uninstall -g @kevinoconnell/mcpkit
Remove-Item -Recurse -Force "$env:USERPROFILE\.mcpkit"
```
## Troubleshooting Installation
If you encounter permission errors on macOS/Linux, you have two options:
**Option 1: Use a Node version manager (recommended)**
```bash theme={null}
# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
# Install Node.js
nvm install 18
nvm use 18
# Now install mcpkit
npm install -g @kevinoconnell/mcpkit
```
**Option 2: Use sudo (not recommended)**
```bash theme={null}
sudo npm install -g @kevinoconnell/mcpkit
```
Using sudo with npm can cause permission issues. We recommend using a Node version manager instead.
If `mcpkit` command is not found after installation:
1. **Check npm global bin path:**
```bash theme={null}
npm config get prefix
```
2. **Add npm bin to PATH:**
macOS/Linux (add to `~/.bashrc` or `~/.zshrc`):
```bash theme={null}
export PATH="$(npm config get prefix)/bin:$PATH"
```
Windows: Add the npm global bin path to your system PATH environment variable.
3. **Restart your terminal** and try again.
MCPKit requires Node.js 18 or later. Update Node.js:
**Using nvm (recommended):**
```bash theme={null}
nvm install 18
nvm use 18
```
**Or download from:**
[nodejs.org](https://nodejs.org)
If installation hangs or fails:
1. **Clear npm cache:**
```bash theme={null}
npm cache clean --force
```
2. **Use a different registry:**
```bash theme={null}
npm install -g @kevinoconnell/mcpkit --registry=https://registry.npmjs.org/
```
3. **Try with verbose logging:**
```bash theme={null}
npm install -g @kevinoconnell/mcpkit --verbose
```
## Next Steps
Create your first MCP server in 5 minutes
Learn about all available commands
# Quickstart
Source: https://mcpkit.sh/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)
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!
## 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
```
You should see the version number printed to the console.
## 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
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:
```bash theme={null}
mcpkit create https://news.ycombinator.com
```
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.
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.
MCPKit will automatically discover actions like:
* Searching for articles
* Reading article content
* Extracting comments
* Navigating pages
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:
```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
```
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"
Make sure to provide the absolute path to `dist/index.js` if you're adding the server from a different directory.
## What's Next?
Learn about all available MCPKit commands
See example MCP servers for different websites
Learn how to save and reuse authentication contexts
Customize and extend your MCP servers
## Common Issues
Make sure your Browserbase API key is valid and you have an active internet connection.
```bash theme={null}
# 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](http://www.example.com) vs example.com)
* You have write permissions to `~/.mcpkit/contexts/`
## Need Help?
Get help from the community
Report bugs or request features