CLI & Gateway Guide

The Go Micro CLI provides two gateway modes for accessing your microservices: development (micro run) and production (micro server). Both use the same underlying gateway architecture, ensuring consistent behavior across environments.

Overview

                    ┌─────────────────────┐
                    │   HTTP Requests     │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │   Unified Gateway   │
                    │                     │
                    │  • Service Discovery│
                    │  • HTTP → RPC       │
                    │  • Web Dashboard    │
                    │  • Health Checks    │
                    └──────────┬──────────┘
                               │
                    ┌──────────▼──────────┐
                    │   Your Services     │
                    │  (via Registry)     │
                    └─────────────────────┘

Quick Comparison

Feature	`micro run`	`micro server`
Purpose	Local development	Production API gateway
Authentication	Yes (default `admin`/`micro`)	Yes (default `admin`/`micro`)
Process Management	Yes (builds & runs services)	No (services run separately)
Hot Reload	Yes (watches file changes)	No
Endpoint Scopes	Yes (`/auth/scopes`)	Yes (`/auth/scopes`)
Best For	Coding, testing, iteration	Deployed environments

Development Mode: `micro run`

Quick Start

bash

# Create and run a service
micro new myservice
cd myservice
micro run

Open http://localhost:8080 - no login required!

What You Get

Instant Gateway: HTTP API at /api/{service}/{method}
Web Dashboard: Browse and test services at /
Hot Reload: Code changes trigger automatic rebuild
Authentication: JWT auth with default credentials (admin/micro)
Scopes: Endpoint access control via /auth/scopes

Example Usage

bash

# Start with hot reload
micro run

# Log in at http://localhost:8080 with admin/micro
# Or use a token for API calls:
curl -X POST http://localhost:8080/api/myservice/Handler.Call \
  -H "Authorization: Bearer <token>" \
  -d '{"name": "World"}'

When to Use

Writing new services
Testing changes locally
Debugging service interactions
Testing auth and scopes before production

See micro run guide for full details.

Production Mode: `micro server`

Quick Start

bash

# Start your services separately (e.g., via systemd, docker)
./myservice &

# Start the gateway
micro server --address :8080

Open http://localhost:8080 and log in with admin/micro.

What You Get

API Gateway: Secure HTTP endpoint for all services
JWT Authentication: Token-based access control
Web Dashboard: Service management UI with login
User Management: Create users and API tokens
Endpoint Scopes: Fine-grained access control per endpoint
Production Ready: Designed for deployed environments

Authentication

All API calls require an Authorization header:

bash

# Get a token (via web UI or login endpoint)
TOKEN="eyJhbGc..."

# Call a service with auth
curl -X POST http://localhost:8080/api/myservice/Handler.Call \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"name": "World"}'

Managing Users, Tokens & Scopes

Log in: Visit http://localhost:8080 → Enter admin/micro
Create API Token: Go to /auth/tokens → Generate token with scopes
Set Endpoint Scopes: Go to /auth/scopes → Restrict which endpoints require which scopes
Use Token: Copy and use in Authorization: Bearer <token> header

When to Use

Production deployments
Staging environments
Multi-team access (with auth)
Public-facing APIs (with security)

Gateway Features (Both Modes)

Both commands provide the same core gateway capabilities:

1. HTTP to RPC Translation

The gateway automatically converts HTTP requests to RPC calls:

bash

POST /api/{service}/{method}
Content-Type: application/json

{"field": "value"}

Becomes an RPC call to:

Service: {service}
Method: {method}
Payload: {"field": "value"}

2. Service Discovery

The gateway queries the registry (mdns, consul, etcd) to find services:

bash

# List all services
curl http://localhost:8080/services

# Returns:
[
  {"name": "myservice", "endpoints": ["Handler.Call", "Handler.List"]},
  {"name": "users", "endpoints": ["Users.Create", "Users.Get"]}
]

Services register automatically when they start - no manual configuration needed!

3. Web Dashboard

Visit / in your browser to:

Browse all registered services
See available endpoints with request/response schemas
Test endpoints with auto-generated forms
View service health and status
Read API documentation

4. Health Checks

bash

# Aggregate health of all services
curl http://localhost:8080/health

# Kubernetes-style probes
curl http://localhost:8080/health/live   # Is gateway alive?
curl http://localhost:8080/health/ready  # Are services ready?

5. Dynamic Updates

The gateway automatically picks up:

New services registering
Services going offline
Endpoint changes
Version updates

No gateway restart needed!

6. Endpoint Scopes

Scopes provide fine-grained access control over which tokens can call which endpoints. Both micro run and micro server support scopes.

Set up endpoint scopes:

Visit /auth/scopes to see all discovered endpoints
Set required scopes for endpoints (e.g., billing on payments.Payments.Charge)
Use Bulk Set to apply scopes to all endpoints matching a pattern (e.g., greeter.*)

Create scoped tokens:

Visit /auth/tokens and create a token with matching scopes
A token with scope billing can call endpoints that require billing
A token with scope * bypasses all scope checks
Endpoints with no scopes set are open to any authenticated token

Scopes are enforced on all call paths:

Direct API calls (/api/{service}/{endpoint})
MCP tool calls (/mcp/call)
Streamable-HTTP MCP tool calls (/mcp)
WebSocket MCP tool calls (/mcp/ws)
Agent playground tool invocations

The gateway uses auth.Account from the go-micro framework. The account's Scopes field carries the same []string used by the framework's wrapper/auth package for service-level auth.

7. MCP Gateway (AI Tool Access)

Every discovered service endpoint is an AI-callable MCP tool. The MCP gateway is its own server, independent of the HTTP API gateway — --mcp-address starts it alongside the HTTP gateway and the CLI shuts both down gracefully when the first one exits or a signal arrives.

bash

# Dashboard/API on :8080 + MCP gateway on :3000
micro gateway --mcp-address :3000

# With production controls on the MCP gateway (scopes, rate limiting, audit, x402)
micro gateway --mcp-address :3000 --auth --audit --rate-limit 100

# Development loop, same flag
micro run --mcp-address :3000

The MCP gateway serves four transports on its address (:3000 in the examples):

Streamable-HTTP at /mcp — spec-compliant JSON-RPC 2.0; the endpoint for browser MCP clients (CORS enabled)
WebSocket at /mcp/ws — bidirectional streaming for agent frameworks
Legacy REST at /mcp/tools and /mcp/call — simple tool listing and calls
Stdio via micro mcp serve — for local CLI agents (Claude Code)

Scopes set in /auth/scopes are enforced on MCP tool calls across all transports. See the MCP guide for the full walkthrough.

Architecture Benefits

Why Unified?

Previously, micro run and micro server had separate gateway implementations. This caused:

❌ Duplicated code (hard to maintain)
❌ Feature lag (improvements didn't benefit both)
❌ Inconsistent behavior between dev and prod

The unified gateway means:

✅ Single codebase for both commands
✅ Identical HTTP API in dev and production
✅ New features benefit both modes automatically
✅ Easier testing and maintenance

What Changed for Users?

From a user perspective:

micro run and micro server both have auth enabled
Both use the same JWT authentication and scopes system
API endpoints are unchanged
Web UI is identical

The unification is internal - your code keeps working.

Common Patterns

Local Development → Production

bash

# 1. Develop locally without auth
micro run
# Test: curl http://localhost:8080/api/...

# 2. Build for production
go build -o myservice

# 3. Deploy services
./myservice &  # or via systemd, docker, k8s

# 4. Start gateway with auth
micro server

# 5. Generate API token (via web UI)
# Use token in production API calls

Multi-Service Development

bash

# micro.mu
service api
    path ./api
    port 8081

service worker
    path ./worker
    port 8082
    depends api

service web
    path ./web
    port 8090
    depends api worker

# Start all with gateway
micro run

See micro run guide for configuration details.

API Gateway Deployment

Deploy micro server as your API gateway in front of all services:

                Internet
                    │
            ┌───────▼────────┐
            │  micro server  │  :8080 (public)
            │   + JWT Auth   │
            └───────┬────────┘
                    │
        ┌───────────┼───────────┐
        │           │           │
    ┌───▼───┐   ┌──▼───┐   ┌──▼────┐
    │ users │   │ posts│   │comments│
    │ :8081 │   │ :8082│   │ :8083  │
    └───────┘   └──────┘   └────────┘
    (internal)  (internal)  (internal)

Only micro server needs public access - services can be internal.

Programmatic Usage

You can also use the gateway in your own Go code:

package main

import (
    "context"
    "log"
    "go-micro.dev/v6/cmd/micro/server"
    "go-micro.dev/v6/store"
)

func main() {
    // Start gateway with custom options
    gw, err := server.StartGateway(server.GatewayOptions{
        Address:     ":9000",
        AuthEnabled: true,  // Enable authentication
        Store:       store.DefaultStore,
        Context:     context.Background(),
    })
    if err != nil {
        log.Fatal(err)
    }

    log.Printf("Gateway running on %s", gw.Addr())

    // Block until context is cancelled
    gw.Wait()
}

This gives you full control over gateway configuration in custom deployments.

Troubleshooting

Gateway starts but no services show

Problem: http://localhost:8080 shows empty service list

Solution:

Check services are running: ps aux | grep myservice
Verify registry: services must register via mdns/consul/etcd
Check logs: ~/micro/logs/ for service startup errors

API calls return 404

Problem: curl http://localhost:8080/api/myservice/Handler.Call returns 404

Solution:

Visit http://localhost:8080/services to see registered endpoints
Check exact endpoint name (case-sensitive): Handler.Call vs handler.call
Ensure service is registered: micro services or check web UI

Authentication errors

Problem: API returns 401 Unauthorized

Solution:

Generate token: Visit http://localhost:8080/auth/tokens
Use header: Authorization: Bearer <token>
Check token not expired (24h default)
Verify user not deleted (tokens revoked on user deletion)

Scope errors

Problem: API returns 403 Forbidden with insufficient scopes

Solution:

Check which scopes the endpoint requires: Visit /auth/scopes
Ensure your token has a matching scope (check at /auth/tokens)
Use a token with * scope for full access
Clear scopes from the endpoint if it should be unrestricted

Port already in use

Problem: micro run or micro server won't start

Solution:

bash

# Check what's using port 8080
lsof -i :8080

# Use different port
micro run --address :9000
micro server --address :9000

Next Steps

Getting Started - Build your first service
micro run Guide - Full development workflow
Deployment Guide - Deploy to production
Architecture - How it works internally

Need Help?

Issues: github.com/micro/go-micro/issues
Discord: discord.gg/G8Gk5j3uXr
Docs: go-micro.dev/docs

Overview

Quick Comparison

Development Mode: micro run

Quick Start

What You Get

Example Usage

When to Use

Production Mode: micro server

Quick Start

What You Get

Authentication

Managing Users, Tokens & Scopes

When to Use

Gateway Features (Both Modes)

1. HTTP to RPC Translation

2. Service Discovery

3. Web Dashboard

4. Health Checks

5. Dynamic Updates

6. Endpoint Scopes

7. MCP Gateway (AI Tool Access)

Architecture Benefits

Why Unified?

What Changed for Users?

Common Patterns

Local Development → Production

Multi-Service Development

API Gateway Deployment

Programmatic Usage

Troubleshooting

Gateway starts but no services show

API calls return 404

Authentication errors

Scope errors

Port already in use

Next Steps

Need Help?

Development Mode: `micro run`

Production Mode: `micro server`