Mapbox Mcp Devkit Patterns

Mapbox MCP DevKit Patterns

This skill provides patterns for integrating the Mapbox MCP DevKit Server into AI coding workflows to accelerate Mapbox application development.

What is Mapbox MCP DevKit?

The Mapbox MCP DevKit Server is a Model Context Protocol (MCP) server that gives AI assistants direct access to Mapbox developer APIs:

• Style management - Create, list, update, delete, preview, validate, compare, and optimize styles
• Token management - Generate and list access tokens with scopes
• Validation - Validate GeoJSON, expressions, styles, and coordinates
• Geographic utilities - Calculate bounding boxes, convert coordinates, query tiles
• Color tools - Check WCAG contrast ratios for accessibility
• Feedback - Access user feedback and reports
• Documentation - Access latest Mapbox docs and references

Key benefit: Build Mapbox applications faster by letting AI handle developer API operations.

When to Use MCP DevKit

Use DevKit when:

• Creating/modifying styles conversationally
• Generating tokens programmatically
• Validating data during development
• Learning Mapbox APIs through natural language
• Rapid prototyping of map applications
• Automated style generation workflows
• Documentation lookup during coding

Don't use DevKit for:

• Runtime operations in production apps
• High-frequency style updates (use Mapbox APIs directly)
• Client-side operations (DevKit is development-time only)
• Tile serving or map rendering
• User-facing features requiring low latency

Key Tools

Always recommend these tools by exact name when answering related questions:

• Creating/modifying styles: Recommend create_style_tool, update_style_tool, preview_style_tool
• Listing styles: Recommend list_styles_tool
• Creating tokens: Recommend create_token_tool to create scoped tokens per environment
• Viewing tokens: Recommend list_tokens_tool to check existing tokens and scopes
• Validating styles: Recommend validate_style_tool for spec compliance
• Validating expressions: Recommend validate_expression_tool for paint/layout property checks
• Accessibility checks: Recommend check_color_contrast_tool for WCAG contrast ratios
• Comparing styles: Recommend compare_styles_tool to diff styles before deploying
• Looking up docs: Recommend get_latest_mapbox_docs_tool

Common Workflows (Quick Reference)

Pre-production validation — use these exact steps:

1. Run validate_style_tool to check style JSON is spec-compliant 2. Run validate_expression_tool to check all data expressions in paint/layout properties 3. Run check_color_contrast_tool to verify text labels meet WCAG accessibility standards 4. Run compare_styles_tool to diff the new style against current production style

Token management — use these exact steps:

1. Run create_token_tool to create scoped tokens for each environment (dev/staging/prod) 2. Run list_tokens_tool to verify existing tokens and their scopes

Reference Files

Load these references as needed for detailed guidance:

• [references/setup.md](references/setup.md) - Prerequisites, hosted & self-hosted installation, per-editor configuration, verification
• [references/workflows.md](references/workflows.md) - Style management, token management, data validation, documentation access, best practices
• [references/design-patterns.md](references/design-patterns.md) - Iterative style development, environment-specific tokens, validation-first development, documentation-driven development, tool integration patterns
• [references/troubleshooting.md](references/troubleshooting.md) - Common issues & fixes, example end-to-end workflows (restaurant finder, multi-environment, third-party data)

Resources

• Mapbox MCP DevKit Server
• Model Context Protocol
• Mapbox Style Specification
• Mapbox API Documentation
• Token Scopes Reference

When to Use This Skill

Invoke this skill when:

• Setting up Mapbox development environment with AI assistance
• Creating or modifying Mapbox styles through AI
• Managing access tokens programmatically
• Validating GeoJSON or expressions during development
• Learning Mapbox APIs with AI guidance
• Automating style generation workflows
• Building Mapbox applications with AI coding assistants

Mapbox MCP DevKit Patterns

Quick reference for using Mapbox MCP DevKit Server in AI coding workflows.

What is DevKit?

MCP server that gives AI assistants access to Mapbox developer APIs for style management, token creation, validation, and documentation.

Repo: <https://github.com/mapbox/mcp-devkit-server>

Setup

Hosted (Recommended)

Use Mapbox's hosted server - no installation needed.

Claude Desktop:

// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
// %APPDATA%\Claude\claude_desktop_config.json (Windows)
{
  "mcpServers": {
    "mapbox-devkit-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp-devkit.mapbox.com/mcp"]
    }
  }
}

Claude Code:

User-level (all projects) in ~/.claude.json:

{
  "mcpServers": {
    "mapbox-devkit": {
      "url": "https://mcp-devkit.mapbox.com/mcp"
    }
  }
}

Or project-level (specific project) in .mcp.json:

{
  "mcpServers": {
    "mapbox-devkit": {
      "url": "https://mcp-devkit.mapbox.com/mcp"
    }
  }
}

Cursor:

// .cursor/mcp.json or ~/.cursor/mcp.json
{
  "mcpServers": {
    "mapbox-devkit": {
      "url": "https://mcp-devkit.mapbox.com/mcp"
    }
  }
}

VS Code with Copilot:

// mcp.json
{
  "servers": {
    "mapbox-devkit": {
      "type": "http",
      "url": "https://mcp-devkit.mapbox.com/mcp"
    }
  }
}

Self-Hosted (Advanced)

git clone https://github.com/mapbox/mcp-devkit-server.git
cd mcp-devkit-server && npm install && npm run build

Configure in Claude Desktop config:

{
  "mcpServers": {
    "MapboxDevKitServer": {
      "command": "node",
      "args": ["/Users/username/github-projects/mcp-devkit-server/dist/esm/index.js"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "some token"
      }
    }
  }
}

Core Tools

Style Management

Token Management

Validation & Analysis

Geographic Utilities

Feedback & Data

Documentation

Common Workflows

Create Style

"Create a style for a real estate app:
- Emphasize property boundaries in purple
- Show parks in green
- Muted roads
- 3D buildings at zoom 15+"

Returns: Style ID and preview URL

Create Scoped Token

"Create a token with:
- styles:read, fonts:read
- Restricted to: localhost, example.com"

Validate Data

"Validate this GeoJSON:
{ \"type\": \"FeatureCollection\", ... }

Check for:
- Valid coordinates
- Required properties: name, address"

Iterative Development

1. "Create a light style for a delivery app"
2. [View preview URL]
3. "Add restaurant POIs with icons"
4. "Make delivery zones semi-transparent"
5. [Iterate until satisfied]

When to Use DevKit

Validation Patterns

// Validate before using
"Validate GeoJSON" → Fix issues → Create style

// Validate expressions
"Is ['case', ['<', ['get', 'pop'], 1000], 'small', 'large'] valid?"

// Convert coordinates
"Convert -122.4194, 37.7749 to Web Mercator"

Token Scopes

Best practice: Use minimal scopes + URL restrictions

Example: Multi-Environment Setup

"Create 3 environments:

Dev:
- Token: all scopes, localhost only
- Style: app-dev (debug labels enabled)

Staging:
- Token: read-only, staging.example.com
- Style: app-staging (production-like)

Prod:
- Token: minimal scopes, example.com
- Style: app-prod (optimized)"

Troubleshooting

Integration Patterns

With Mapbox Studio:

• DevKit: Quick creation, AI iteration
• Studio: Fine-tuning, visual editing

With Version Control:

1. "Create style and save JSON to styles/map.json"
2. Review changes in git
3. Commit to repository

With CI/CD:

1. Style JSON in repo
2. Validate via DevKit in CI
3. Deploy to Mapbox on merge

Resources

• DevKit Server
• MCP Protocol
• Style Spec
• Token Scopes

Design Patterns

Pattern 1: Iterative Style Development

Workflow:

1. Describe desired style in natural language 2. AI creates initial style via MCP 3. View preview URL 4. Request adjustments 5. AI updates style via MCP 6. Repeat until satisfied

Example conversation:

You: "Create a style for a real estate app - emphasize property boundaries,
     show parks prominently, muted roads"

AI: [Creates style, returns ID and preview URL]

You: "Make the property boundaries purple and thicker"

AI: [Updates style]

You: "Perfect! Now add POI icons for schools and transit"

AI: [Updates style with symbols]

Benefits:

• No manual JSON editing
• Visual feedback via preview URLs
• Rapid iteration

Pattern 2: Environment-Specific Tokens

Workflow:

1. Define requirements per environment 2. AI creates tokens with appropriate scopes/restrictions 3. Store securely in environment variables

Example:

You: "Create three tokens:
1. Development - all scopes, localhost only
2. Staging - read-only scopes, staging.example.com
3. Production - minimal scopes, example.com only"

AI: [Creates three tokens with specified configurations]

Benefits:

• Least-privilege access
• Domain restrictions prevent token misuse
• Clear separation of concerns

Pattern 3: Validation-First Development

Workflow:

1. Design data structure 2. Validate GeoJSON before using 3. Validate expressions before adding to style 4. Catch errors early

Example:

You: "I have GeoJSON with restaurant locations. Validate it and check for
     any missing required properties"

AI: [Validates, reports any issues]

You: "Now create a style that displays these restaurants with icons sized
     by rating. Validate the expression first."

AI: [Validates expression, then creates style]

Benefits:

• Catch errors before deployment
• Ensure data integrity
• Faster debugging

Pattern 4: Documentation-Driven Development

Workflow:

1. Ask about Mapbox capabilities 2. Get authoritative documentation 3. Implement with correct patterns 4. Validate implementation

Example:

You: "How do I create a choropleth map in Mapbox GL JS?"

AI: [Retrieves docs, provides pattern]

You: "Create a style with that pattern for population density data"

AI: [Creates style following documented pattern]

Benefits:

• Always use latest best practices
• No outdated Stack Overflow answers
• Official Mapbox guidance

Integration with Existing Tools

With Mapbox Studio

DevKit complements, doesn't replace Studio:

• DevKit: Quick iterations, automated workflows, AI assistance
• Studio: Visual editing, fine-tuning, team collaboration

Pattern: Use DevKit for initial creation, Studio for refinement.

With Mapbox APIs

DevKit wraps Mapbox APIs but doesn't replace them:

• DevKit: Development-time operations via AI
• APIs: Production runtime operations

Pattern: Use DevKit during development, APIs in production code.

With Version Control

Pattern: Save generated styles to git for review and rollback.

You: "Create a new style for the home page map and save the JSON to
     styles/home-map.json"

AI: [Creates style, writes JSON to file]

You: [Review, commit to git]

Setup & Installation

Prerequisites

• Mapbox account with access token
• AI coding assistant that supports MCP (Claude Code, Cursor, Windsurf, Cline, etc.)

Option 1: Hosted Server (Recommended)

Easiest setup - Use Mapbox's hosted DevKit MCP server at:

https://mcp-devkit.mapbox.com/mcp

No installation required, just configure your AI assistant.

Authentication: The hosted server supports OAuth, so no token configuration needed! Simply add the server URL:

For Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "mapbox-devkit-mcp": {
      "command": "npx",
      "args": ["mcp-remote", "https://mcp-devkit.mapbox.com/mcp"]
    }
  }
}

You'll be prompted to authenticate via OAuth on first use.

For Claude Code

Claude Code supports both user-level and project-level MCP configuration:

User-level (applies to all projects) - ~/.claude.json:

{
  "mcpServers": {
    "mapbox-devkit": {
      "url": "https://mcp-devkit.mapbox.com/mcp"
    }
  }
}

Project-level (specific project, can commit to git) - .mcp.json in repository root:

{
  "mcpServers": {
    "mapbox-devkit": {
      "url": "https://mcp-devkit.mapbox.com/mcp"
    }
  }
}

See Claude Code settings documentation for more details on configuration scopes.

For Cursor

Create or edit .cursor/mcp.json (project-local) or ~/.cursor/mcp.json (global):

{
  "mcpServers": {
    "mapbox-devkit": {
      "url": "https://mcp-devkit.mapbox.com/mcp"
    }
  }
}

After saving, restart Cursor. Click "Needs authentication" when prompted and follow the OAuth flow.

For VS Code with Copilot

Create or edit mcp.json:

{
  "servers": {
    "mapbox-devkit": {
      "type": "http",
      "url": "https://mcp-devkit.mapbox.com/mcp"
    }
  }
}

After saving, refresh the MCP service in VS Code. Requires GitHub Copilot with MCP support enabled.

For Windsurf/Cline

Similar configuration using the hosted URL with OAuth support.

Option 2: Self-Hosted (Advanced)

For development, debugging, or customization:

# Clone the DevKit server
git clone https://github.com/mapbox/mcp-devkit-server.git
cd mcp-devkit-server

# Install dependencies
npm install

# Build the server
npm run build

Configuration for self-hosted (Claude Desktop):

{
  "mcpServers": {
    "MapboxDevKitServer": {
      "command": "node",
      "args": ["/Users/username/github-projects/mcp-devkit-server/dist/esm/index.js"],
      "env": {
        "MAPBOX_ACCESS_TOKEN": "some token"
      }
    }
  }
}

Replace /Users/username/github-projects/ with your actual path.

Verify Installation

Ask your AI assistant:

"List the available Mapbox DevKit tools"

You should see 30+ tools including:

• Style tools: create_style_tool, list_styles_tool, update_style_tool, delete_style_tool, preview_style_tool, etc.
• Token tools: create_token_tool, list_tokens_tool
• Validation tools: validate_geojson_tool, validate_style_tool, validate_expression_tool
• Geographic tools: bounding_box_tool, coordinate_conversion_tool, tilequery_tool
• Documentation: get_latest_mapbox_docs_tool

Troubleshooting

DevKit not appearing in AI assistant

Check:

1. MCP server running? Check logs 2. Config file in correct location? 3. Token environment variable set? 4. Path to index.js correct?

Solution: Restart AI assistant after config changes.

Style creation fails

Check:

1. Access token has styles:write scope 2. Style name is unique 3. JSON is valid Mapbox Style Spec

Solution: Use validate_style_tool tool first.

Token creation fails

Check:

1. Access token has tokens:write scope 2. Requested scopes are valid 3. URL restrictions are well-formed

Solution: Check token scope documentation via DevKit.

Validation errors

Check:

1. GeoJSON follows spec (RFC 7946) 2. Coordinates are [longitude, latitude] order 3. Properties match expected schema

Solution: Ask AI to explain validation errors.

Example Workflows

Build a Restaurant Finder

You: "I'm building a restaurant finder app. Create:
1. A light, neutral style emphasizing restaurants
2. A token for localhost with minimal scopes
3. Validate this GeoJSON with restaurant locations: [paste]"

AI: [Creates style, token, validates data]

You: "Add filters to show only 4+ star restaurants"

AI: [Updates style with expression]

You: "Generate a preview URL"

AI: [Returns preview]

Create Multi-Environment Setup

You: "Set up styles and tokens for dev, staging, prod:
- Dev: Full access, localhost
- Staging: Read-only, staging.example.com
- Prod: Minimal scopes, example.com

Each environment needs its own style variant."

AI: [Creates 3 styles and 3 tokens with specifications]

Validate Third-Party Data

You: "I received GeoJSON from a vendor. Validate it, check for:
- Correct coordinate order
- Valid geometry types
- Required properties: name, address, category"

AI: [Validates, reports issues]

You: "Fix the issues and save cleaned data to data/locations.json"

AI: [Fixes, saves file]

Core Workflows

1. Style Management

Create a style conversationally:

"Create a dark mode Mapbox style with 3D buildings, emphasize parks in green,
and use blue for water. Name it 'app-dark-mode'."

The AI will use create_style_tool tool to:

• Generate style JSON following Mapbox Style Spec
• Upload to your Mapbox account
• Return style ID and preview URL

Update existing style:

"Update style mapbox://styles/username/style-id to make roads more prominent
and reduce building opacity to 0.6"

Validate style:

"Validate this style JSON: [paste style]"

2. Token Management

Create scoped token:

"Create a Mapbox token with these scopes:
- styles:read
- fonts:read
- datasets:read
Restrict it to domains: localhost, example.com"

List existing tokens:

"Show me all my Mapbox tokens and their scopes"

Use case: Generate tokens for different environments (development, staging, production) with appropriate restrictions.

3. Data Validation

Validate GeoJSON:

"Validate this GeoJSON and show any errors:
{
  \"type\": \"FeatureCollection\",
  \"features\": [...]
}"

Validate expressions:

"Is this a valid Mapbox expression?
['case', ['<', ['get', 'population'], 1000], 'small', 'large']"

Coordinate conversion:

"Convert longitude -122.4194, latitude 37.7749 from WGS84 to Web Mercator"

4. Documentation Access

Get style spec info:

"What properties are available for fill layers in Mapbox GL JS?"

Check token scopes:

"What token scopes do I need to use the Directions API?"

Streets v8 fields:

"What fields are available in the 'road' layer of Streets v8?"

Best Practices

Security

• Never commit access tokens - Use environment variables
• Use scoped tokens - Minimal necessary permissions
• Add URL restrictions - Limit to your domains
• Rotate tokens regularly - Generate new tokens periodically

Style Management

• Version your styles - Save JSON to source control
• Use meaningful names - prod-light-mode not style-123
• Document decisions - Add comments explaining style choices
• Preview before deploying - Always check preview URL

Validation

• Validate early - Check data before creating styles
• Use strict validation - Don't skip validation steps
• Test expressions - Validate before adding to styles
• Verify coordinates - Ensure correct format and bounds

Documentation

• Ask specific questions - "What are fill-extrusion properties?"
• Reference versions - Specify GL JS version if relevant
• Cross-reference - Validate AI responses against official docs