May 24, 2026 · 4 min read

How to Set Up MCP Servers with Grok Build (2026)

Grok Build supports MCP (Model Context Protocol) servers out of the box. This means you can connect it to your filesystem, GitHub repos, databases, Slack, and any custom tool server without writing integration code.

This guide walks through setup, configuration, and practical examples for the most useful MCP servers.

How MCP works in Grok Build

MCP servers expose tools and resources that Grok Build can call during a session. When you ask Grok Build to “check the latest GitHub issues” or “query the users table,” it routes those requests through the connected MCP server.

The flow:

You configure MCP servers in Grok Build’s config
Grok Build discovers available tools from each server at startup
During a session, Grok Build calls these tools as needed
Results feed back into the agent’s context

Configuration file location

Scope	Path
Global (all projects)	`~/.grok/mcp.json`
Project-level	`.grok/mcp.json`

Project-level configs override global configs for the same server name.

Basic config format

{
  "servers": {
    "server-name": {
      "command": "command to start the server",
      "env": {
        "ENV_VAR": "value"
      }
    }
  }
}

Setup via CLI

You can also add servers without editing JSON:

# Add a server
grok mcp add <name> --command "<command>" --env KEY=VALUE

# List servers
grok mcp list

# Remove a server
grok mcp remove <name>

# Test connection
grok mcp test <name>

Example 1: Filesystem server

Gives Grok Build read/write access to specific directories outside your project.

grok mcp add filesystem --command "npx @modelcontextprotocol/server-filesystem /home/user/documents"

Or in ~/.grok/mcp.json:

{
  "servers": {
    "filesystem": {
      "command": "npx @modelcontextprotocol/server-filesystem /home/user/documents"
    }
  }
}

Use case: Access shared config files, documentation, or data directories that live outside your project root.

Example 2: GitHub server

grok mcp add github --command "npx @modelcontextprotocol/server-github" --env GITHUB_TOKEN=ghp_your_token

Config file version:

{
  "servers": {
    "github": {
      "command": "npx @modelcontextprotocol/server-github",
      "env": {
        "GITHUB_TOKEN": "ghp_your_token"
      }
    }
  }
}

Available tools: Create issues, read PRs, search repos, list branches, read file contents from remote repos.

Example 3: PostgreSQL server

grok mcp add postgres --command "npx @modelcontextprotocol/server-postgres" --env DATABASE_URL=postgresql://user:pass@localhost:5432/mydb

{
  "servers": {
    "postgres": {
      "command": "npx @modelcontextprotocol/server-postgres",
      "env": {
        "DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Available tools: Run queries, list tables, describe schemas, explain query plans.

Example 4: Slack server

{
  "servers": {
    "slack": {
      "command": "npx @modelcontextprotocol/server-slack",
      "env": {
        "SLACK_BOT_TOKEN": "xoxb-your-token",
        "SLACK_TEAM_ID": "T0123456"
      }
    }
  }
}

Available tools: Send messages, read channels, search messages, list users.

Example 5: Custom/local server

If you’ve built your own MCP server:

{
  "servers": {
    "my-internal-api": {
      "command": "node /path/to/my-mcp-server/index.js",
      "env": {
        "API_BASE_URL": "https://internal.company.com/api",
        "API_KEY": "secret"
      }
    }
  }
}

Multiple servers in one config

{
  "servers": {
    "filesystem": {
      "command": "npx @modelcontextprotocol/server-filesystem /home/user/docs"
    },
    "github": {
      "command": "npx @modelcontextprotocol/server-github",
      "env": {
        "GITHUB_TOKEN": "ghp_xxx"
      }
    },
    "postgres": {
      "command": "npx @modelcontextprotocol/server-postgres",
      "env": {
        "DATABASE_URL": "postgresql://localhost:5432/mydb"
      }
    }
  }
}

Verifying server connections

# Check all servers
grok mcp list

# Test a specific server
grok mcp test github

# Inside a session, see available tools
/mcp

The /mcp slash command shows all connected servers and their available tools during an active session.

Project-level vs global config

Use global (~/.grok/mcp.json) for:

Personal GitHub token
General-purpose filesystem access
Slack/communication tools

Use project-level (.grok/mcp.json) for:

Project-specific database connections
Internal API servers
Custom tools relevant only to this codebase

Project-level configs are great for team sharing. Add .grok/mcp.json to your repo (minus secrets) and use environment variable references:

{
  "servers": {
    "postgres": {
      "command": "npx @modelcontextprotocol/server-postgres",
      "env": {
        "DATABASE_URL": "$DATABASE_URL"
      }
    }
  }
}

Grok Build resolves $DATABASE_URL from your shell environment at startup.

Security considerations

MCP servers run locally on your machine
They have whatever access their command grants (filesystem paths, database credentials)
Keep tokens out of version control. Use environment variable references
The grok mcp test command verifies connectivity without exposing credentials in output

Combining MCP with Skills

MCP servers provide raw tool access. Skills/Plugins provide higher-level workflows that can use MCP tools internally. For example, a “database migration” skill might use the PostgreSQL MCP server under the hood.

For the full Grok Build setup, see the complete guide.

FAQ

How many MCP servers can I connect simultaneously?

There’s no hard limit documented. Users report running 5-8 servers without issues. Each server adds startup time (1-2 seconds) and consumes some context for tool descriptions.

Do MCP servers consume tokens?

Yes. Each tool call sends a request and receives a response, both of which count toward your token usage. A database query might use 200-500 tokens for the request/response cycle. On the API plan, this adds to your bill. On SuperGrok, it’s included.

Can I use the same MCP servers I use with Claude Code?

Yes, the same server packages work. The config format is slightly different (see our migration guide). The MCP protocol is standardized, so any compliant server works with any compliant client.

What happens if an MCP server crashes mid-session?

Grok Build handles disconnections gracefully. It reports the tool as unavailable and continues working without it. You can restart the server and it reconnects automatically.

Can I restrict which tools Grok Build can call?

Not at the config level currently. If you want to limit access, configure the MCP server itself with restricted permissions (e.g., read-only database user, limited filesystem paths).

Do MCP servers work in headless mode?

Yes. MCP servers start and connect the same way in headless (grok -p "prompt") mode. This is useful for CI/CD pipelines that need database access or GitHub integration.