Skip to content

json-mcp-clients-setup.md

Latest commit

 

History

History
149 lines (106 loc) · 3.76 KB

json-mcp-clients-setup.md

File metadata and controls

149 lines (106 loc) · 3.76 KB

JSON-Based MCP Clients Setup Guide

This guide is for clients such as Factory AI Droid, OpenClaw, and OpenCode when they support MCP server configuration through a JSON-based settings file or MCP settings UI.

Note: this is a schema-agnostic, best-effort guide. It intentionally avoids claiming exact official file locations or wrapper schemas for these clients unless the format is explicitly verified.

Important note

Different clients use different top-level schemas and file locations.

Because those client-specific schemas can vary, this guide does not assume a single exact file path or wrapper format. Instead, it gives you reusable server blocks for @zereight/mcp-gitlab that you can place inside the client's MCP configuration structure.

Use the local stdio server fields that your client expects and map in these values:

  • command
  • args
  • env

Reusable PAT server block

{
  "command": "npx",
  "args": ["-y", "@zereight/mcp-gitlab"],
  "env": {
    "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-your-token",
    "GITLAB_API_URL": "https://gitlab.com/api/v4",
    "GITLAB_READ_ONLY_MODE": "false"
  }
}

Reusable OAuth server block

{
  "command": "npx",
  "args": ["-y", "@zereight/mcp-gitlab"],
  "env": {
    "GITLAB_USE_OAUTH": "true",
    "GITLAB_OAUTH_CLIENT_ID": "your-client-id",
    "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
    "GITLAB_API_URL": "https://gitlab.com/api/v4"
  }
}

If your OAuth app is confidential, also add:

{
  "GITLAB_OAUTH_CLIENT_SECRET": "your-client-secret"
}

Example wrappers

If your client expects an mcpServers object:

{
  "mcpServers": {
    "gitlab": {
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-your-token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

If your client expects a servers object:

{
  "servers": {
    "gitlab": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@zereight/mcp-gitlab"],
      "env": {
        "GITLAB_PERSONAL_ACCESS_TOKEN": "glpat-your-token",
        "GITLAB_API_URL": "https://gitlab.com/api/v4"
      }
    }
  }
}

Client-specific notes

Factory AI Droid

Use the local stdio MCP server fields supported by the Droid MCP configuration flow. Reuse the server block above and adapt it to the exact Droid wrapper schema exposed by your Droid version.

OpenClaw

If OpenClaw exposes an MCP JSON configuration surface, reuse the same command / args / env block and place it inside the client's expected wrapper format.

OpenCode

If OpenCode exposes a JSON MCP configuration format, reuse the same stdio server block and adapt it to the required top-level schema for that release or integration surface.

Common mistakes

1. Using the GitLab web URL instead of the API URL

Use:

  • https://gitlab.com/api/v4

not:

  • https://gitlab.com

2. Missing OAuth client secret for confidential apps

Only public OAuth apps can omit GITLAB_OAUTH_CLIENT_SECRET.

3. Wrong wrapper schema

Your client may require:

  • mcpServers
  • servers
  • or a settings UI with separate fields

The inner server block remains the same, but the outer wrapper can differ.

4. Hardcoding secrets in shared config

If the client supports secret prompts, environment files, or injected env vars, prefer those over committing secrets to source control.

Recommended first prompt

List my GitLab projects and show me recent merge requests.

See also