From adda4c542cfd79ba5a32c18bdea61da24e1bdbb9 Mon Sep 17 00:00:00 2001 From: Andres Garcia Date: Thu, 22 Oct 2026 14:43:04 +0000 Subject: [PATCH 1/2] knowledge_base: add mcp_and_model_services example Add a bundle that defines an AI Gateway model service routed to a Databricks pay-per-token foundation model and an MCP service backed by a schema-level Unity Catalog connection, both in a bundle-managed schema. Co-authored-by: Isaac Co-authored-by: omnigent --- .../mcp_and_model_services/.gitignore | 1 + .../mcp_and_model_services/README.md | 41 +++++++++++++++++++ .../mcp_and_model_services/databricks.yml | 21 ++++++++++ .../resources/ai_services.schema.yml | 5 +++ .../resources/chat.model_service.yml | 14 +++++++ .../resources/docs.mcp_service.yml | 10 +++++ 6 files changed, 92 insertions(+) create mode 100644 knowledge_base/mcp_and_model_services/.gitignore create mode 100644 knowledge_base/mcp_and_model_services/README.md create mode 100644 knowledge_base/mcp_and_model_services/databricks.yml create mode 100644 knowledge_base/mcp_and_model_services/resources/ai_services.schema.yml create mode 100644 knowledge_base/mcp_and_model_services/resources/chat.model_service.yml create mode 100644 knowledge_base/mcp_and_model_services/resources/docs.mcp_service.yml diff --git a/knowledge_base/mcp_and_model_services/.gitignore b/knowledge_base/mcp_and_model_services/.gitignore new file mode 100644 index 00000000..15bcc6dd --- /dev/null +++ b/knowledge_base/mcp_and_model_services/.gitignore @@ -0,0 +1 @@ +.databricks diff --git a/knowledge_base/mcp_and_model_services/README.md b/knowledge_base/mcp_and_model_services/README.md new file mode 100644 index 00000000..4e5daf21 --- /dev/null +++ b/knowledge_base/mcp_and_model_services/README.md @@ -0,0 +1,41 @@ +# MCP and model services + +This Declarative Automation Bundles example defines an AI Gateway model service and an MCP service in a Unity Catalog schema. +The model service routes chat requests to a Databricks foundation model. The MCP service exposes the tools of an external MCP server. + +For more information, see the [bundle resources documentation](https://docs.databricks.com/aws/en/dev-tools/bundles/resources#model_services). + +## Prerequisites + +* Databricks CLI v1.20.0 or above +* A Unity Catalog catalog where you can create schemas +* A schema-level HTTP connection to an MCP server. See [Register an external MCP server](https://docs.databricks.com/aws/en/ai-gateway/register-mcp-service). + +## Usage + +1. Deploy the bundle. Replace the values with your catalog and connection: + ```bash + databricks bundle deploy --var catalog=main --var mcp_connection=main.default.my_mcp_connection + ``` + +2. Send a chat request to the model service. Use the schema name from `databricks bundle summary`: + ```bash + databricks api post /ai-gateway/mlflow/v1/chat/completions --json '{ + "model": "main.dev__ai_services.chat", + "messages": [{"role": "user", "content": "What is Databricks?"}] + }' + ``` + +3. List the MCP tools. Get a token from `databricks auth token`: + ```bash + curl -X POST "https:///ai-gateway/mcp-services/main.dev__ai_services.docs" \ + -H "Authorization: Bearer " \ + -H "Accept: application/json, text/event-stream" \ + -H "Content-Type: application/json" \ + -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' + ``` + +4. Remove the services and the schema: + ```bash + databricks bundle destroy --var catalog=main --var mcp_connection=main.default.my_mcp_connection + ``` diff --git a/knowledge_base/mcp_and_model_services/databricks.yml b/knowledge_base/mcp_and_model_services/databricks.yml new file mode 100644 index 00000000..c79f8ceb --- /dev/null +++ b/knowledge_base/mcp_and_model_services/databricks.yml @@ -0,0 +1,21 @@ +bundle: + name: mcp_and_model_services + # AI Gateway services can only be deployed with the direct deployment engine. + engine: direct + +include: + - resources/*.yml + +variables: + catalog: + description: Existing Unity Catalog catalog for the services schema. + default: main + mcp_connection: + description: Schema-level HTTP connection to an MCP server, as catalog.schema.connection. + +targets: + dev: + mode: development + default: true + workspace: + root_path: /Workspace/bundle-examples/${bundle.name}/${bundle.target}/${workspace.current_user.short_name} diff --git a/knowledge_base/mcp_and_model_services/resources/ai_services.schema.yml b/knowledge_base/mcp_and_model_services/resources/ai_services.schema.yml new file mode 100644 index 00000000..3eada6de --- /dev/null +++ b/knowledge_base/mcp_and_model_services/resources/ai_services.schema.yml @@ -0,0 +1,5 @@ +resources: + schemas: + ai_services: + catalog_name: ${var.catalog} + name: ai_services diff --git a/knowledge_base/mcp_and_model_services/resources/chat.model_service.yml b/knowledge_base/mcp_and_model_services/resources/chat.model_service.yml new file mode 100644 index 00000000..05a07621 --- /dev/null +++ b/knowledge_base/mcp_and_model_services/resources/chat.model_service.yml @@ -0,0 +1,14 @@ +resources: + model_services: + chat: + parent: schemas/${resources.schemas.ai_services.id} + model_service_id: chat + comment: Routes chat requests to a Databricks foundation model. + config: + routing: + destinations: + - name: primary + destination_type: DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL + pay_per_token_config: + # Any pay-per-token model in system.ai works here. + model: models/system.ai.databricks-claude-sonnet-4-6 diff --git a/knowledge_base/mcp_and_model_services/resources/docs.mcp_service.yml b/knowledge_base/mcp_and_model_services/resources/docs.mcp_service.yml new file mode 100644 index 00000000..eedb7c64 --- /dev/null +++ b/knowledge_base/mcp_and_model_services/resources/docs.mcp_service.yml @@ -0,0 +1,10 @@ +resources: + mcp_services: + docs: + parent: schemas/${resources.schemas.ai_services.id} + mcp_service_id: docs + comment: Exposes the tools of an external MCP server. + config: + source_connection: + # The connection holds the MCP server URL and credentials. + name: connections/${var.mcp_connection} From a7e280020426f6862f0b5eed853750c156397477 Mon Sep 17 00:00:00 2001 From: Andres Garcia Date: Thu, 22 Oct 2026 14:52:56 +0000 Subject: [PATCH 2/2] knowledge_base/mcp_and_model_services: address review feedback Make catalog and the foundation model required variables, use a literal dev segment in root_path, and add an Anthropic model provider service with relayed authentication so no provider key is stored. The README MCP step now derives the host and token from the CLI. Co-authored-by: Isaac Co-authored-by: omnigent --- .../mcp_and_model_services/README.md | 27 ++++++++++--------- .../mcp_and_model_services/databricks.yml | 6 +++-- .../anthropic.model_provider_service.yml | 12 +++++++++ .../resources/chat.model_service.yml | 3 +-- 4 files changed, 32 insertions(+), 16 deletions(-) create mode 100644 knowledge_base/mcp_and_model_services/resources/anthropic.model_provider_service.yml diff --git a/knowledge_base/mcp_and_model_services/README.md b/knowledge_base/mcp_and_model_services/README.md index 4e5daf21..53ea7684 100644 --- a/knowledge_base/mcp_and_model_services/README.md +++ b/knowledge_base/mcp_and_model_services/README.md @@ -1,41 +1,44 @@ # MCP and model services -This Declarative Automation Bundles example defines an AI Gateway model service and an MCP service in a Unity Catalog schema. -The model service routes chat requests to a Databricks foundation model. The MCP service exposes the tools of an external MCP server. +This Declarative Automation Bundles example defines an AI Gateway model service, a model provider service, and an MCP service in a Unity Catalog schema. +The model service routes chat requests to a Databricks foundation model. The model provider service connects to Anthropic with relayed authentication. The MCP service exposes the tools of an external MCP server. For more information, see the [bundle resources documentation](https://docs.databricks.com/aws/en/dev-tools/bundles/resources#model_services). ## Prerequisites -* Databricks CLI v1.20.0 or above +* Databricks CLI v1.20.0 or above, authenticated with OAuth (`databricks auth login`) +* `jq` * A Unity Catalog catalog where you can create schemas * A schema-level HTTP connection to an MCP server. See [Register an external MCP server](https://docs.databricks.com/aws/en/ai-gateway/register-mcp-service). ## Usage -1. Deploy the bundle. Replace the values with your catalog and connection: +1. Select a pay-per-token foundation model from the `system.ai` schema, for example `system.ai.databricks-claude-sonnet-4-6`. + +2. Deploy the bundle. Replace the placeholders with your catalog, model, and connection: ```bash - databricks bundle deploy --var catalog=main --var mcp_connection=main.default.my_mcp_connection + databricks bundle deploy --var catalog= --var chat_model= --var mcp_connection= ``` -2. Send a chat request to the model service. Use the schema name from `databricks bundle summary`: +3. Send a chat request to the model service. The schema name is `.dev__ai_services`: ```bash databricks api post /ai-gateway/mlflow/v1/chat/completions --json '{ - "model": "main.dev__ai_services.chat", + "model": ".dev__ai_services.chat", "messages": [{"role": "user", "content": "What is Databricks?"}] }' ``` -3. List the MCP tools. Get a token from `databricks auth token`: +4. List the tools of the MCP service. The command gets the host and a token from the CLI: ```bash - curl -X POST "https:///ai-gateway/mcp-services/main.dev__ai_services.docs" \ - -H "Authorization: Bearer " \ + curl -X POST "$(databricks auth describe --output json | jq -r .details.host)/ai-gateway/mcp-services/.dev__ai_services.docs" \ + -H "Authorization: Bearer $(databricks auth token | jq -r .access_token)" \ -H "Accept: application/json, text/event-stream" \ -H "Content-Type: application/json" \ -d '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' ``` -4. Remove the services and the schema: +5. Remove the services and the schema: ```bash - databricks bundle destroy --var catalog=main --var mcp_connection=main.default.my_mcp_connection + databricks bundle destroy --var catalog= --var chat_model= --var mcp_connection= ``` diff --git a/knowledge_base/mcp_and_model_services/databricks.yml b/knowledge_base/mcp_and_model_services/databricks.yml index c79f8ceb..48da65b3 100644 --- a/knowledge_base/mcp_and_model_services/databricks.yml +++ b/knowledge_base/mcp_and_model_services/databricks.yml @@ -9,7 +9,9 @@ include: variables: catalog: description: Existing Unity Catalog catalog for the services schema. - default: main + chat_model: + # Example: system.ai.databricks-claude-sonnet-4-6 + description: Pay-per-token foundation model in system.ai, as catalog.schema.model. mcp_connection: description: Schema-level HTTP connection to an MCP server, as catalog.schema.connection. @@ -18,4 +20,4 @@ targets: mode: development default: true workspace: - root_path: /Workspace/bundle-examples/${bundle.name}/${bundle.target}/${workspace.current_user.short_name} + root_path: /Workspace/bundle-examples/${bundle.name}/dev/${workspace.current_user.short_name} diff --git a/knowledge_base/mcp_and_model_services/resources/anthropic.model_provider_service.yml b/knowledge_base/mcp_and_model_services/resources/anthropic.model_provider_service.yml new file mode 100644 index 00000000..47167a06 --- /dev/null +++ b/knowledge_base/mcp_and_model_services/resources/anthropic.model_provider_service.yml @@ -0,0 +1,12 @@ +resources: + model_provider_services: + anthropic: + parent: schemas/${resources.schemas.ai_services.id} + model_provider_service_id: anthropic + comment: Anthropic provider with relayed authentication. + config: + provider_type: EXTERNAL_MODEL_PROVIDER_TYPE_ANTHROPIC + allow_all_targets: true + anthropic: + # Each request supplies its own Anthropic credential. No key is stored. + relayed: {} diff --git a/knowledge_base/mcp_and_model_services/resources/chat.model_service.yml b/knowledge_base/mcp_and_model_services/resources/chat.model_service.yml index 05a07621..aceb9f52 100644 --- a/knowledge_base/mcp_and_model_services/resources/chat.model_service.yml +++ b/knowledge_base/mcp_and_model_services/resources/chat.model_service.yml @@ -10,5 +10,4 @@ resources: - name: primary destination_type: DESTINATION_TYPE_PAY_PER_TOKEN_FOUNDATION_MODEL pay_per_token_config: - # Any pay-per-token model in system.ai works here. - model: models/system.ai.databricks-claude-sonnet-4-6 + model: models/${var.chat_model}