Connecting AI Agents to DataHub Core: The MCP Server, Permissions and Semantic Search

AI agents are becoming a new kind of DataHub user. Instead of a person searching the catalog, an assistant in an IDE or chat client asks DataHub which table holds revenue, who owns it and what feeds it. DataHub’s answer to this is a Model Context Protocol (MCP) server, and alongside it a semantic search capability for natural-language questions.

This article explains what the MCP server exposes to agents in a self-hosted DataHub Core deployment, how authentication and write access work, what semantic search requires, and where the limits are. It is written for teams deciding whether to let agents into their catalog, and on what terms.

What changed: the catalog as context for agents

The DataHub MCP server guide, shown for release 1.7.0 on the research date, describes two ways to run the server. DataHub Cloud offers a managed endpoint. For DataHub Core, you run the open-source mcp-server-datahub yourself, either per user or as a shared HTTP service; the guide states that this “works with any DataHub instance”.

The release stream shows where the project is heading. On the DataHub GitHub releases page, the 1.8.0 release candidates published in September and October 2026 include an in-process ONNX embedding provider for semantic search. A 1.6.0.3 patch release in September 2026 focused on security and authorisation hardening and required Python 3.11 on that line. Version 1.8.0 was not final on the research date.

Several features in the guide are specific to DataHub Cloud, including the managed endpoint, OAuth sign-in through the tenant’s single sign-on, and one-click client plugins. This article covers the self-hosted Core route. Capabilities differ by edition and, for Cloud, by contract.

What an agent can see and do

The MCP server groups its tools into read and write sets. The guide lists, among others:

Group	Examples of tools	Effect
Discovery	search, get_entities, list_schema_fields, get_lineage, get_lineage_paths_between	Read metadata, schemas and lineage
Documents	search_documents, grep_documents	Read context documents; hidden when none exist
SQL context	get_dataset_queries, find_sql_context, draft_sql_for_tables	Read query history and draft SQL; nothing is executed against a warehouse by these tools
Mutation	add or remove tags, terms, owners and domains; update_description; save_document; propose_* tools	Change metadata in DataHub

Write tools are off unless enabled. The guide states that TOOLS_IS_MUTATION_ENABLED=true turns them on, from mcp-server-datahub v0.5.0. Each write tool is annotated as not read-only, so MCP clients can ask the user for confirmation before calling it.

The read tools already cover the questions analysts ask most often. An agent can find candidate datasets, list their fields, follow lineage upstream to a source system, and look at how a table is usually queried before drafting SQL. Because the answers come from the catalog, they reflect whatever ownership, descriptions and lineage your ingestion has captured, including lineage from tools such as dbt and query engines.

Our default recommendation is to start read-only. Discovery and lineage questions deliver most of the early value. Write tools change shared governance metadata, so enable them only after you have decided who reviews agent-made changes and how they are attributed.

Authentication and permissions in a shared deployment

The MCP server acts with the identity of the token it presents to DataHub. That makes the deployment pattern a security decision.

• Per-user, local. A developer runs the server locally with DATAHUB_GMS_URL and a personal access token in DATAHUB_GMS_TOKEN. Permissions match that person.
• Shared HTTP service. One server serves many users at /mcp, and each request carries the user’s own bearer token. The guide states that shared deployments need mcp-server-datahub v0.7.0 or later, because earlier versions have no per-request authentication. The server refuses to start if DATAHUB_GMS_TOKEN is set in this mode, and the DataHub instance needs METADATA_SERVICE_AUTH_ENABLED=true.
• Service accounts. For unattended or agentic workflows, the guide recommends service accounts rather than personal tokens. A service account can have a Default View that limits which assets the MCP server searches; on Core this requires v1.6.0 or later.

Two operational details are easy to miss. Tokens must be sent in the Authorization header; the guide notes that a token query parameter is rejected. And the shared server exposes an unauthenticated GET /health endpoint for probes, which should be reachable only from your monitoring network.

Per-user tokens keep search results, permissions and audit attribution separate. A single shared token is simpler, and it makes every agent action look like one user. We advise against it for anything beyond a pilot.

Semantic search and context documents

Keyword search needs matching terms. The semantic search guide describes natural-language search using vector embeddings, so a question about requesting data access can find a document titled “Data Access Request Process” without sharing its words. Semantic search is additive; keyword search remains.

The design has two halves that must agree. Document embeddings are created at ingestion time and written as a SemanticContent aspect. Query embeddings are created at search time by the DataHub metadata service. Both must use the same embedding model. The guide lists OpenAI, AWS Bedrock, Cohere and a local ONNX model as providers; a classical provider exists for CI and smoke tests and is not semantic search.

Context documents are fed through the DataHub Documents source, which the documentation marks as Alpha. It chunks markdown documents, embeds the chunks in batches and skips unchanged documents using a content hash. Its requirements include OpenSearch 2.17 or later with the k-NN plugin, or Elasticsearch 8.18 or later, plus an embedding provider and semantic search enabled in the server configuration.

Documents can be created through the GraphQL API or the Python SDK, or brought in from external sources such as Notion or Confluence, according to the same page. The source can run in event-driven mode, reacting to metadata change events on Kafka, or in batch mode over GraphQL. Event-driven mode keeps embeddings closer to current content; batch mode is easier to schedule and reason about.

The trade-offs are concrete:

• Data leaves the platform with hosted providers. With OpenAI, Bedrock or Cohere, document text is sent to that provider for embedding. A local ONNX model avoids this, at the cost of running and sizing the model yourself.
• Search infrastructure changes. Your search cluster must meet the version and k-NN requirements. The guide describes writes to two indices during a transitional period, which adds storage and indexing load.
• Alpha status. The Documents source is not yet a stable interface. Pin versions and expect changes between releases.

What the MCP server does not do

An MCP server makes the catalog easier to query. It does not change what DataHub is responsible for.

• It does not enforce data access. DataHub’s policies govern who can read and edit metadata. Access to the data itself is still enforced by the query engines and security systems, such as Trino or your warehouse.
• It does not make metadata correct. An agent answers from descriptions, owners and lineage as they are. Stale ownership or missing lineage produce confident but wrong answers.
• It does not remove prompt-injection risk. Descriptions, documents and query text are content written by many people. Treat tool results as data, not instructions, in the agent’s design, and keep write tools behind confirmation.

Designing a pilot

A useful pilot is small and measurable. Pick one domain with good ownership and lineage, and a group of analysts who already use the catalog. Give them a read-only MCP connection with their own tokens, and collect the questions they ask, the answers they receive and where those answers were wrong.

The results usually point to metadata gaps rather than to the agent. Missing descriptions, outdated owners and incomplete lineage show up quickly when someone asks a direct question. Fixing those gaps benefits human users too, which makes the pilot worthwhile even if agent adoption stays limited.

Only after that review should you consider write tools or semantic search. Each adds a new operational surface: governance review for agent-made changes, and an embedding pipeline with its own provider, index and failure modes.

A rollout checklist

• Confirm the DataHub Core version and the mcp-server-datahub version; v0.7.0 or later for a shared deployment.
• Enable metadata service authentication on the DataHub instance before exposing a shared server.
• Issue per-user tokens or service accounts with Default Views; avoid one shared personal token.
• Start with read-only tools; record who approves enabling TOOLS_IS_MUTATION_ENABLED.
• Restrict network access to the MCP endpoint and the health probe.
• For semantic search, choose an embedding provider with your data-protection team and confirm search cluster versions.
• Pin the Documents source version while it is Alpha, and monitor ingestion failures.
• Fix ownership and lineage gaps in priority domains before inviting agents in.

How Bassirah can help

We help teams deploy and secure the DataHub MCP server on DataHub Core, decide on token and service-account patterns, and evaluate semantic search and its infrastructure needs. Our DataHub support is independent engineering; upstream fixes follow the community’s timeline. See our DataHub page and data governance for how we approach catalog work, and enterprise AI AgentOps for running agents in production.