MCP StoneX UDP Genie

A simple, production-ready template for building Model Context Protocol (MCP) servers using FastMCP and FastAPI. This project demonstrates how to create custom tools that AI assistants can discover and invoke.

🚀 Quickstart Setup Guide

Follow these steps to deploy and connect your MCP StoneX UDP Genie App:

0. Update the Repository

• Add or update tools as needed.

• Note: You currently need to define a separate tool for each Genie.

1. Launch as a Databricks App

Run the following commands in your project directory:

2. Assign App Permissions

For the auto-created App Service Principal, grant ALL of the following permissions in Databricks:

• CAN USE on the App

• CAN RUN on the Genie Space

• USE CATALOG on the Genie Space's catalog target

• USE SCHEMA on the Genie Space's schema target

• SELECT on all tables in the Genie Space's schema target

3. Create a Databricks App Connection

1. Go to Databricks Account Console

2. Go to Settings → App Connections.

3. Click Add Connection.

4. Set up as follows:

   • REDIRECT_URL:
     {databricks_app_url}/.auth/callback

   • CLIENT_SECRET:
     YES (copy & save for step 4)

   • OAUTH_ACCESS_SCOPE:
     all-apis

4. Configure an External UC Connection

Fill in the following values:

5. Add to Playground or Supervisor

• Register the External MCP Server in Playground or Multi-agent Supervisor for testing and multi-agent experiments.

Key Concepts

• Tools: Callable functions that AI assistants can invoke (e.g., search databases, process data, call APIs)

• Server: Exposes tools via the MCP protocol over HTTP

• Client: Applications (like Claude, AI assistants) that discover and call tools

Features

• ✅ FastMCP-based server with HTTP streaming support

• ✅ FastAPI integration for additional REST endpoints

• ✅ Example tools: health check and user information

• ✅ Production-ready project structure

• ✅ Ready for Databricks Apps deployment

Project Structure

Prerequisites

• Python 3.11 or higher

• uv (recommended) or pip

Installation

Option 1: Using uv (Recommended)

Option 2: Using pip

Running the Server

Development Mode

The server will start on http://localhost:8000 by default (or your specified port).

Accessing the Server

• MCP Endpoints: http://localhost:8000/mcp

• Available Tools:

  • health: Check server status

  • get_current_user: Get authenticated user information

Testing the MCP Server

This project includes test scripts to verify your MCP server is working correctly in both local and deployed environments.

Integration Tests

The project includes automated integration tests that validate the MCP server functionality:

What the tests do:

• Automatically start the MCP server

• Test that list_tools() works correctly

• Test that all registered tools can be called without errors by invoking the call_tools()

• Automatically clean up the server after tests complete

Manual Testing

End-to-end test your locally-running MCP server

The script connects to your local MCP server without authentication and lists available tools.

End-to-end test your deployed MCP server

After deploying to Databricks Apps, use the interactive shell script to test with user-level OAuth authentication:

The script will guide you through:

1. Profile selection: Choose your Databricks CLI profile

2. App name: Enter your deployed app name

3. Automatic configuration: Extracts app scopes and URLs automatically

4. OAuth flow: Generates user OAuth token via browser

5. End-to-end test: Tests list_tools(), and invokes each tool returned in list_tools

What it does:

• Retrieves app configuration using databricks apps get

• Extracts user authorization scopes from effective_user_api_scopes

• Gets workspace host from your Databricks profile

• Generates OAuth token with the correct scopes

• Tests MCP client with user-level authentication

• Verifies both the health check and get_current_user tool work correctly

This test simulates the real end-user experience when they authorize your app and use it with their credentials.

Alternatively, test manually with command-line arguments:

The scripts/dev/query_remote.py script connects to your deployed MCP server with OAuth authentication and tests both the health check and user authorization functionality.

Adding New Tools

To add a new tool to your MCP server:

1. Open server/tools.py

2. Add a new function inside load_tools() with the @mcp_server.tool decorator:

3. Restart the server - the new tool will be automatically available to clients

Tool Best Practices

• Clear naming: Use descriptive, action-oriented names

• Comprehensive docstrings: AI uses these to understand when to call your tool

• Type hints: Help with validation and documentation

• Structured returns: Return dicts or Pydantic models for consistent data

• Error handling: Use try-except blocks and return error information

Connecting to Databricks

The utils.py module provides two helper methods for interacting with Databricks resources via the Databricks SDK Workspace Client:

When deployed as a Databricks App:

• get_workspace_client() - Returns a client authenticated as the service principal associated with the app. See App Authorization for more details.

• get_user_authenticated_workspace_client() - Returns a client authenticated as the end user with scopes specified by the app creator. See User Authorization for more details.

When running locally:

• Both methods return a client authenticated as the current developer, since no service principal identity exists in the local environment.

Example usage in tools:

See the get_current_user tool in server/tools.py for a complete example.

Generating OAuth Tokens

For advanced use cases, you can manually generate OAuth tokens for Databricks workspace access using the provided script. This implements the OAuth U2M (User-to-Machine) flow.

Generate Workspace-Level OAuth Token

Parameters:

• --host: Databricks workspace URL (required)

• --scopes: Space-separated OAuth scopes (default: all-apis offline_access)

• --redirect-uri: Callback URI (default: http://localhost:8020)

Note: The script uses the databricks-cli OAuth client ID by default.

The script will:

1. Generate a PKCE code verifier and challenge

2. Open your browser for authorization

3. Capture the authorization code via local HTTP server

4. Exchange the code for an access token

5. Display the token response as JSON (token is valid for 1 hour)

Example with custom scopes:

Configuration

Server Settings

The server can be configured using command-line arguments:

The default configuration:

• Host: 0.0.0.0 (listens on all network interfaces)

• Port: 8000 (configurable via --port argument)

Deployment

Databricks Apps

This project is configured for Databricks Apps deployment:

1. Deploy using Databricks CLI or UI

2. The server will be accessible at your Databricks app URL

For more information refer to the documentation here

Try Your MCP Server in AI Playground

After deploying your MCP server to Databricks Apps, you can test it interactively in the Databricks AI Playground:

1. Navigate to the AI Playground in your Databricks workspace

2. Select a model with the Tools enabled label

3. Click Tools > + Add tool and select your deployed MCP server

4. Start chatting with the AI agent - it will automatically call your MCP server's tools as needed

The AI Playground provides a visual interface to prototype and test your MCP server with different models and configurations before integrating it into production applications.

For more information, see Prototype tool-calling agents in AI Playground.

Development

Code Formatting

Customization

Rename the Project

1. Update name in pyproject.toml

2. Update name parameter in server/app.py: FastMCP(name="your-name")

3. Update the command script in pyproject.toml under [project.scripts]

Add Custom API Endpoints

Add routes to the app FastAPI instance in server/app.py:

Troubleshooting

Port Already in Use

Change the port in server/main.py or set the PORT environment variable.

Import Errors

Ensure all dependencies are installed:

Resources

• Databricks MCP Documentation

• Databricks Apps

• FastMCP Documentation

• Model Context Protocol Specification

• FastAPI Documentation

• Uvicorn Documentation

AI Assistant Context

See Claude.md for detailed project context specifically designed for AI assistants working with this codebase.