Golden Path — From Zero to Prod in ~30 Minutes

Set up Hatago MCP Hub inside an existing Node.js project and reach a practical, shareable setup fast.

🎯 Goals

Hatago integrated into your project
At least one MCP server connected
Environment separation via tags
Self‑diagnosis steps for errors
Ready to share with the team

✅ Preflight

Node version
Terminal window
```
node --version  # v20.0.0+
```
In project root
Terminal window
```
pwd && ls package.json
```
(Optional) Global prefix
Terminal window
```
npm config get prefix
```

🚀 Step 1: Install (2 min)

npm install --save-dev @himorishige/hatago-mcp-hub

# Add scripts
npm pkg set scripts.mcp="hatago serve"
npm pkg set scripts.mcp:dev="hatago serve --tags dev --watch"
npm pkg set scripts.mcp:prod="hatago serve --tags production"

pnpm add -D @himorishige/hatago-mcp-hub
pnpm pkg set scripts.mcp="hatago serve"
pnpm pkg set scripts.mcp:dev="hatago serve --tags dev --watch"
pnpm pkg set scripts.mcp:prod="hatago serve --tags production"

yarn add -D @himorishige/hatago-mcp-hub
# Add scripts manually to package.json

🔧 Step 2: Init (3 min)

Create config

npx @himorishige/hatago-mcp-hub init --mode stdio

Create env file

cat > .env.local << 'EOF'
# Hatago MCP Hub
MCP_LOG_LEVEL=info
NODE_ENV=development
# OPENAI_API_KEY=sk-...
# GITHUB_TOKEN=ghp_...
EOF

gitignore

echo -e "\n# Hatago MCP Hub\nhatago-config.local.json\n.env.local" >> .gitignore

📦 Step 3: First server (5 min)

Edit config

{
  "$schema": "https://raw.githubusercontent.com/himorishige/hatago-hub/main/schemas/config.schema.json",
  "version": 1,
  "logLevel": "info",
  "mcpServers": {
    "filesystem-local": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"],
      "cwd": ".",
      "tags": ["dev", "local", "filesystem"],
      "env": { "NODE_ENV": "${NODE_ENV:-development}" }
    }
  }
}

Run
Terminal window
```
npm run mcp:dev
```

Direct check

echo '{"jsonrpc":"2.0","method":"tools/list","id":1,"params":{}}' | npx @himorishige/hatago-mcp-hub serve --stdio

🏷️ Step 4: Environments via tags (5 min)

Add dev/mock/prod servers and start with tags.

{
  "mcpServers": {
    "filesystem-local": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "./src"],
      "tags": ["dev", "local", "filesystem"]
    },
    "mock-api": {
      "command": "node",
      "args": ["./scripts/mock-server.js"],
      "tags": ["dev", "mock", "api"],
      "disabled": false
    },
    "production-api": {
      "url": "https://api.production.example.com/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer ${PROD_API_TOKEN}" },
      "tags": ["production", "api", "remote"],
      "disabled": false
    }
  }
}

Start by environment:

npm run mcp:dev
PROD_API_TOKEN=xxx npm run mcp:prod

🧪 Step 5: Verify (5 min)

Create a tiny verification script:

#!/usr/bin/env node
const { spawn } = require('child_process');
const readline = require('readline');
async function verify() {
  const tests = [
    { name: 'read servers resource', req: { jsonrpc: '2.0', method: 'resources/read', id: 1, params: { uri: 'hatago://servers' } } }
  ];
  const hatago = spawn('npx', ['@himorishige/hatago-mcp-hub', 'serve', '--stdio'], { stdio: ['pipe','pipe','pipe'] });
  const rl = readline.createInterface({ input: hatago.stdout, crlfDelay: Infinity });
  let i = 0; hatago.stdin.write(JSON.stringify(tests[0].req)+'\n');
  rl.on('line', (line) => {
    try {
      const res = JSON.parse(line); console.log('✅', tests[i].name);
      if (++i < tests.length) hatago.stdin.write(JSON.stringify(tests[i].req)+'\n'); else { console.log('🎉 done'); hatago.kill(); process.exit(0); }
    } catch (e) { console.error('❌', e.message); hatago.kill(); process.exit(1); }
  });
}
verify().catch(console.error);

Run it:

node scripts/verify-hatago.js

🚨 Troubleshooting

Common fixes:

Error	Cause	Fix
`ENOENT: hatago-config.json`	Missing config	`npx @himorishige/hatago-mcp-hub init`
`Invalid JSON`	Broken config	Validate JSON
`${VAR} not found`	Missing env	Export or set in `.env.local`
`Server failed to start`	Child server error	Run with `--verbose`

Template config

cp hatago-config.json hatago-config.example.json

Env template
Terminal window
```
cp .env.local .env.example
```

README snippet

## MCP Hub Setup
1. Install deps: `npm install`
2. Copy config: `cp hatago-config.example.json hatago-config.json`
3. Copy env: `cp .env.example .env.local`
4. Fill `.env.local`
5. Start: `npm run mcp:dev`

✅ Checklist

🎯 Next

Tag Filtering

Remote Servers

Config Inheritance