Skip to content

Library · Data Practice OS

Agents and MCP

Reference guide · Published · Source reviewed

The answer: build an AI agent only when a task genuinely needs several steps across different tools. Most first use cases are a single retrieval or a single SQL question, and a plain call is cheaper, faster and easier to evaluate. When you do need an agent, give it a few narrow, read-only tools, a step and cost budget, full tracing, and an evaluation set.

Picking the platform

Need Default
Business users asking questions across structured metrics and documents Cortex Agents and Snowflake Intelligence with Snowflake Intelligence: orchestrates Cortex Analyst and Cortex Search with little code
Custom multi-step workflows, document extraction at scale, multi-agent supervisors Agent Bricks on Databricks (the agent developer platform that absorbed the Mosaic AI Agent Framework), traced with MLflow
Agent needs to write transactional state (case notes, task queues) Add Lakebase or an operational database. Do not let agents write to gold tables
Agent lives in an existing app or IDE Expose platform data through a managed Model Context Protocol server and call it from the app

This follows the practice's workload split (ADR-001: One platform by default, two only by workload). If only one platform is in place, use its agent tooling.

MCP: the integration seam

The Model Context Protocol lets any compliant client (Claude, internal apps, IDE assistants) discover and call tools. Both platforms offer managed MCP servers:

  • Snowflake-managed MCP server serves Cortex Analyst, Cortex Search and Cortex Agents as tools, plus custom tools and SQL execution. It uses Snowflake OAuth by default, or External OAuth against The organisation's identity provider, and RBAC on the server and on each tool: access to the server does not grant the tools. Snowflake recommends exposing a Cortex Agent as the client-facing tool for business data (docs).
  • Databricks managed MCP endpoints serve Genie spaces, AI Search indexes, Databricks SQL and Unity Catalog functions (Public Preview; a workspace admin enables them), each with its own OAuth scope. system.ai MCP services are governed through Unity Gateway (docs).

With OAuth, calls carry the end user's identity, so platform permissions still apply. Avoid long-lived personal access tokens. Where one is unavoidable, bind it to the least-privileged role.

Rules for MCP tools in the practice:

  • Platform-managed servers first. A custom MCP server is code to own, patch and assess.
  • Identity flows through. No shared service accounts behind an agent that end users drive.
  • Read-only by default. A write tool needs a named owner, a reason, and Human in the loop approval for anything with effect on a customer.
  • Small tool surface. Five well-described tools beat thirty. Tool descriptions are prompts: review them like code.

A minimal agent design

Agent: Road asset defect triage assistant (internal, read-only)
Tools:
  1. asset_metrics      -> Cortex Analyst / Genie over the road-asset semantic model
  2. inspection_search  -> Cortex Search / Databricks AI Search over inspection reports
  3. asset_lookup(id)   -> SQL function returning one asset's attributes
Limits: max 8 tool calls, max 60 s, max $0.20 per conversation
Output: summary + cited sources + suggested priority (advisory only)
Human: engineer confirms priority before any work order is raised
Trace: every step to MLflow / Snowflake AI observability, kept 12 months

Worked example

A district engineer asks: "Which bridges on the Warrego Highway had defects rated severe in the last two inspections, and what did the inspectors recommend?" The agent calls asset_metrics for the bridge list, inspection_search filtered to those asset IDs for recommendations, and returns a table with links. It does not raise work orders. A human does that in the asset management system. The evaluation set includes 60 questions written with district engineers, and a check that no answer cites an asset outside the asked-for corridor.

When not to use an agent

  • One question, one tool: call the tool directly.
  • Deterministic workflows (approve if A and B): write code or a pipeline.
  • Decisions about people (licence suspensions, penalty outcomes): the agent may summarise evidence, but a person decides. See Governance, security and trust.

Pitfalls

  • Unbounded loops. Always set step, time and cost caps, and route calls through the AI gateway so overruns show up.
  • Tool sprawl. Every tool added widens failure modes and the security review.
  • No tracing. If you cannot replay why the agent answered, you cannot fix or defend it.
  • Evaluating only the final answer. Also check tool choice and arguments. MLflow and Agent Bricks support trace-level judges.
  • Prompt injection via documents. Retrieved text is untrusted input. Never let retrieved content change tool scopes, and put Guardrails on outputs.

Related: Evaluating AI systems, RAG and enterprise search, The semantic layer, AI-native patterns.

Lessons from platform options papers

Source: a platform team's draft options papers and platform docs (Oct-Nov 2026). All draft or proposed. None is an agreed decision; treat them as evidence, not standards.

  • Agents do not only run inside the data platforms. In that platform team's work they run in a custom assistant (Bedrock with Neo4j), Copilot Studio, Claude Code and AgentCore. Use platform-managed MCP servers for data that lives on Snowflake or Databricks. For other sources (graph, legislation, SaaS), use a shared custom-server pattern. The platform team's recommendation (in Confluence; no approval is recorded) is FastMCP on ECS Fargate first, with Amazon Bedrock AgentCore Gateway as the target front door. Hosting is decided per server.
  • No general query tool. Never expose a raw execute_sql or execute_cypher tool. Use domain tools with parameterised queries. Text-to-SQL over a governed semantic model with a read-only role is acceptable.
  • Prove Identity propagation for each hop: client to gateway to server to store. Prefer on-behalf-of token exchange over passing tokens through. Where a service role calls the store, the server writes its own audit line (actor, tool, record IDs, request ID). Check that token claims in logs (for example the JWT sub claim in CloudTrail) carry no personal information.
  • Return provenance in every tool result: source document, identifier, section, version or effective date, classification and retrieval time. Evaluation checks that these fields are present.
  • Hosting changes connection behaviour. Serverless hosts open a driver per session or environment, and bursts can exhaust database connection limits. Prefer pooled hosting for data servers that make many calls.
  • Design for the weakest consumer. Microsoft Copilot Studio supported Streamable HTTP only, and tools and resources but not prompts (checked Oct 2026). Power Platform data policies decide which connectors are allowed. Include Power Platform admins as stakeholders.
  • Separate the tool gateway from the model gateway (Tool gateway vs AI gateway). Many architectures need both.
  • Treat tool outputs and memory as untrusted, like retrieved text. See Agent memory.