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

Development Mode: micro run

Quick Start

# 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

# 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

# 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:

# 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

1. Log in: Visit http://localhost:8080 → Enter admin/micro
2. Create API Token: Go to /auth/tokens → Generate token with scopes
3. Set Endpoint Scopes: Go to /auth/scopes → Restrict which endpoints require which scopes
4. 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:

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:

# 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

# 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:

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

Create scoped tokens:

1. Visit /auth/tokens and create a token with matching scopes
2. A token with scope billing can call endpoints that require billing
3. A token with scope * bypasses all scope checks
4. 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.

# 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

# 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

# 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:

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

API calls return 404

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

Solution:

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

Authentication errors

Problem: API returns 401 Unauthorized

Solution:

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

Scope errors

Problem: API returns 403 Forbidden with insufficient scopes

Solution:

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

Port already in use

Problem: micro run or micro server won’t start

Solution:

# 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