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.

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

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?"

Design Patterns

Pattern 1: Iterative Style Development

Workflow:

Describe desired style in natural language
AI creates initial style via MCP
View preview URL
Request adjustments
AI updates style via MCP
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:

Define requirements per environment
AI creates tokens with appropriate scopes/restrictions
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:

Design data structure
Validate GeoJSON before using
Validate expressions before adding to style
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:

Ask about Mapbox capabilities
Get authoritative documentation
Implement with correct patterns
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

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

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]

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

Troubleshooting

DevKit not appearing in AI assistant

Check:

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

Solution: Restart AI assistant after config changes.

Style creation fails

Check:

Access token has styles:write scope
Style name is unique
JSON is valid Mapbox Style Spec

Solution: Use validate_style_tool tool first.

Token creation fails

Check:

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

Solution: Check token scope documentation via DevKit.

Validation errors

Check:

GeoJSON follows spec (RFC 7946)
Coordinates are [longitude, latitude] order
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]

Resources

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