MCP

apx includes a built-in MCP (Model Context Protocol) server that enables AI assistants like Cursor, Claude, VSCode, and Codex to interact with your development environment.

Overview

The MCP server provides tools for:

• Development Server Management - Start, stop, restart, and monitor dev servers
• Code Quality - Check project code for errors
• Component Management - Search and add UI components (with scoring boost for project-configured registries)
• SDK Documentation - Search Databricks SDK documentation
• API Routes - Get route information and code examples
• Deployment Logs - Fetch logs from deployed Databricks Apps
• Feedback - Submit feedback as GitHub issues
• Project Context - Rich project metadata including routes, dependencies, backend files, and configured registries

Starting the MCP Server

apx mcp

The MCP server runs over stdio and integrates with AI assistants that support the Model Context Protocol.

Configuration

Choose your AI assistant to see the configuration:

{
  "mcpServers": {
    "shadcn": {
      "command": "bun",
      "args": ["x", "--bun", "shadcn@latest", "mcp"]
    },
    "apx": {
      "command": "apx",
      "args": ["mcp"]
    }
  }
}

apx dev apply cursor

{
  "mcpServers": {
    "shadcn": {
      "command": "bun",
      "args": ["x", "--bun", "shadcn@latest", "mcp"]
    },
    "apx": {
      "command": "apx",
      "args": ["mcp"]
    },
    "playwright": {
      "command": "apx",
      "args": ["bun", "x", "--bun", "@playwright/mcp@latest"]
    }
  }
}

apx dev apply vscode

{
  "mcpServers": {
    "shadcn": {
      "command": "bun",
      "args": ["x", "--bun", "shadcn@latest", "mcp"]
    },
    "apx": {
      "command": "apx",
      "args": ["mcp"]
    },
    "playwright": {
      "command": "apx",
      "args": ["bun", "x", "--bun", "@playwright/mcp@latest"]
    }
  }
}

apx dev apply claude

apx dev apply codex

Available Tools

Development Server Tools

Component Tools

Project Tools

Documentation Tools

Deployment Tools

Feedback Tools

Tool Details

start

Start the development server in detached mode.

Returns: Server URL (e.g., http://localhost:8000)

stop

Stop all running development servers.

Returns: Confirmation message

restart

Restart development servers, attempting to reuse the same port.

Returns: New server URL

logs

Fetch recent dev server logs.

Parameters:

• duration (optional): Time period for logs (default: 60s)

Returns: Log output from backend, frontend, and OpenAPI watcher

check

Check project code for errors using TypeScript compiler and Python type checker in parallel.

Returns: Check results or error messages

refresh_openapi

Regenerate the OpenAPI schema and TypeScript API client from your Python models.

Returns: Confirmation message

search_registry_components

Search for UI components using semantic search across all cached registries.

Components from registries configured in [tool.apx.ui.registries] (pyproject.toml) receive a scoring boost, improving discoverability of project-relevant components.

Parameters:

• query: Search query (e.g., "button", "data table", "chat message")
• limit (optional): Maximum results (default: 10)

Returns: List of matching components with registry, relevance score, and the project's configured registries

list_registry_components

List all available components in a registry.

Parameters:

• app_path: Absolute path to the project directory
• registry (optional): Registry name (e.g., @animate-ui). Omit for default shadcn registry.

Returns: List of component names in the registry

add_component

Add a UI component to your project.

Parameters:

• component_id: Component identifier
  • Simple: button (from default registry)
  • With registry: @animate-ui/accordion
• force (optional): Overwrite existing files (default: false)

Returns: Confirmation message

routes

List all API routes from the OpenAPI schema.

Parameters:

• app_path: Absolute path to the project directory

Returns: List of API routes with methods, paths, and operation IDs

docs

Search Databricks SDK documentation for relevant code examples.

Parameters:

• source: Documentation source (databricks-sdk-python)
• query: Search query (e.g., "create cluster", "list jobs")
• num_results (optional): Maximum results (default: 5)

Returns: Matching documentation with code examples and source files

get_route_info

Get TypeScript code example for using a specific API route.

Parameters:

• operation_id: Operation ID from OpenAPI schema (e.g., listItems, createItem)

Returns: React hook usage example with types

databricks_apps_logs

Fetch logs from a deployed Databricks App.

Parameters:

• app_name (optional): App name (auto-detected from databricks.yml if not provided)
• tail_lines (optional): Number of lines to fetch (default: 200)
• search (optional): Filter logs by search term
• source (optional): Filter by log source
• profile (optional): Databricks CLI profile
• target (optional): Deployment target
• timeout_seconds (optional): Command timeout (default: 60)

Returns: Log output with metadata

feedback_prepare

Prepare a feedback issue for review before submission.

Parameters:

• title: Issue title
• body: Issue description (markdown)
• labels (optional): Issue labels

Returns: Formatted title, body, and browser URL for review

feedback_submit

Submit a previously prepared feedback issue as a public GitHub issue.

Parameters:

• title: Issue title (from feedback_prepare)
• body: Issue body (from feedback_prepare)

Returns: GitHub issue URL or browser fallback URL

Resources

The MCP server exposes resources that provide project context:

AI Assistant Integration

Workflow Example

Use apx mcp server to start development server, then create a nice
application for order management. Use shadcn mcp to add new components,
make sure style is consistent and data is properly fetched from the backend.

The AI assistant will:

1. Call start to launch the development servers
2. Use search_registry_components to find relevant UI components
3. Call add_component to install components
4. Use get_route_info to understand API usage
5. Use check to verify code quality

Best Practices

1. Let the AI manage servers - AI assistants can start/stop servers as needed
2. Check configured registries first - Components from project-configured registries (in pyproject.toml) are boosted in search results. Use list_registry_components to browse specific registries before building custom components.
3. Leverage SDK docs - Always use the docs tool to verify Databricks SDK method signatures before writing ws.* calls
4. Use SDK methods, not raw HTTP - Prefer ws.jobs.list() over ws.api_client.do(). SDK methods handle pagination, retries, and type safety.
5. Check code regularly - Use the check tool to catch errors early
6. Use get_route_info for frontend - Get ready-to-use Suspense + ErrorBoundary scaffolding for any API route