Skip to main content

Setup & Registration

The MCP server is bundled inside the Metatate Native App. Registration creates the canonical MCP server object, grants access to the app roles, and wires the tool layer to your governance tables. The same deployment also creates the core.agent_* wrapper layer used by Snowflake Intelligence custom tools. Claude Code and Cortex Code connect to the canonical Snowflake-managed MCP server after their client authentication is configured.

Prerequisites​

Before registering the MCP server, ensure:

  1. Metatate is installed -- The Native App (METATATE_APP) must be installed and the backend service running.
  2. APP_WAREHOUSE reference is configured -- The MCP server needs a warehouse to execute procedure-based tools (authorize-use, validate-query-context, explain-why). Bind the APP_WAREHOUSE reference in the Snowflake UI or via SQL:
ALTER APPLICATION METATATE_APP
  SET REFERENCES = ('APP_WAREHOUSE' = '<your_warehouse>');
  1. At least one policy is deployed -- The governance tables must contain data. Deploy a policy through the Metatate UI or API before testing the MCP tools.

Registration​

The MCP server is automatically registered when you run the initialization procedure:

CALL METATATE_APP.v1.init();

init() calls register_mcp_server() internally after configuring schema objects and governance tables. It also runs automatically when the APP_WAREHOUSE reference is first configured.

Manual​

If you need to re-register the MCP server (e.g., after a schema change or troubleshooting), call it directly:

CALL METATATE_APP.v1.register_mcp_server();

This is idempotent -- calling it multiple times is safe. It will drop and recreate the MCP server object if it already exists.

What Registration Creates​

Registration creates the following objects in the core schema:

ObjectTypeDescription
core.metatate_mcpMCP ServerCanonical Metatate machine interface
core.discover_contextFunctionSearches governed tables with optional filters
core.get_decision_contextFunctionReturns full governance context for a table
core.inspect_data_meaningFunctionReturns column-level governance detail
core.inspect_governance_rulesFunctionReturns deployed usage, validation, and transfer rules
core.authorize_useProcedureEvaluates an authorization request against policies
core.validate_query_contextProcedureAnalyzes SQL for governance compliance
core.explain_whyProcedureRetrieves audit trail for a past decision
core.agent_*Functions / ProceduresSnowflake Intelligence-friendly wrappers with scalar parameters

Grants​

Registration grants USAGE on the MCP server and USAGE/EXECUTE on the underlying functions and procedures to both app roles:

  • app_admin -- Full access to all tools
  • app_user -- Full access to all tools (governance is data-driven, not role-gated at the tool level)

Verifying Registration​

Check the MCP Server Exists​

USE APPLICATION METATATE_APP;
SHOW MCP SERVERS IN SCHEMA CORE;

Expected output: one row for METATATE_MCP.

Check the Tools​

SHOW FUNCTIONS IN SCHEMA METATATE_APP.CORE;
SHOW PROCEDURES IN SCHEMA METATATE_APP.CORE;

You should see the canonical tool objects and the core.agent_* wrappers listed in the table above.

Test a Tool Directly​

The fastest way to verify the MCP server is working is to call a function directly:

-- Discover all governed tables (no filters)
SELECT METATATE_APP.CORE.DISCOVER_CONTEXT(
  OBJECT_CONSTRUCT()
);

Expected: A JSON object with status: "success" and a data array containing your governed tables.

-- Get governance context for a specific table
SELECT METATATE_APP.CORE.GET_DECISION_CONTEXT(
  OBJECT_CONSTRUCT('table_name', 'MY_DB.MY_SCHEMA.CUSTOMERS')
);

Test the Snowflake Intelligence wrapper pattern​

You can validate the Snowflake Intelligence adapter layer directly in SQL before wiring it into an agent:

SELECT METATATE_APP.CORE.AGENT_GET_DECISION_CONTEXT('MY_DB.MY_SCHEMA.CUSTOMERS');

This should return the same JSON payload as the canonical GET_DECISION_CONTEXT tool.

In-App Testing​

Metatate includes a Test Tools tab in the application UI. This provides a graphical interface to:

  • Browse all seven tools and their input schemas
  • Fill in parameters with form fields
  • Execute tools and view formatted JSON responses
  • Compare canonical tool payloads with the Snowflake Intelligence wrapper behavior

This is the easiest way to explore the canonical MCP layer without writing SQL or configuring a Snowflake Intelligence agent first.

Claude Code plugin validation​

After the managed MCP server exists, Snowflake administrators can configure OAuth for Claude Code. The Claude Code plugin then connects to:

https://<account-url>/api/v2/databases/METATATE_APP/schemas/CORE/mcp-servers/METATATE_MCP

Use a role-scoped OAuth registration:

session:role:<snowflake-role>

See Claude Code Plugin for the full administrator and user setup flow.

Cortex Code plugin validation​

After the managed MCP server exists, Snowflake administrators can issue a role-restricted PAT for Cortex Code users. The Cortex Code plugin connects to the same endpoint:

https://<account-url>/api/v2/databases/METATATE_APP/schemas/CORE/mcp-servers/METATATE_MCP

Use the plugin helper to register the server with PAT headers:

export METATATE_CORTEX_PAT='<snowflake-pat-secret>'
./bin/metatate-cortex-mcp-add \
  --account-url https://<account-url> \
  --snowflake-role <snowflake-role> \
  --write
cortex mcp start

Expected result:

metatate: 7 tools available

See Cortex Code Plugin for the full administrator and user setup flow.

Wrapper regression script​

To validate the full Snowflake Intelligence adapter layer against a deployed app, run:

snow sql -f scripts/test_snowflake_intelligence_tools.sql

That script seeds acceptance-style governance fixtures, executes all seven core.agent_* wrappers, and cleans up the test data afterward.

Unregistering​

To remove the MCP server (e.g., before uninstalling):

USE APPLICATION METATATE_APP;
DROP MCP SERVER IF EXISTS CORE.METATATE_MCP;

The underlying functions and procedures will remain. Re-run register_mcp_server() to recreate the server object.

Next Steps​