.. include:: /includes.rst.txt

.. comments - headings

   # with overline, for parts
   * with overline, for chapters
   = for sections
   - for subsections
   ^ for subsubsections
   " for paragraphs
   * for H5
   + for H6

.. _mcp_server:

**********
MCP Server
**********

AI assistants can access data stored in TQ Data Foundation via a
`Model Context Protocol (MCP) <https://modelcontextprotocol.io/>`_ server.
This allows users to query and explore asset collections using natural language
through AI tools such as Claude Code, Claude Desktop, OpenAI Codex and
VS Code with GitHub Copilot.

The MCP server is a remote server, reached over HTTPS. Users sign in with their
existing Data Foundation accounts and have access to the same asset collections
they can already access in Data Foundation.

Features
========

The MCP server allows AI assistants to:

- List available asset collections in TQ Data Foundation
- Run read-only SPARQL queries against TQ Data Foundation

Example questions you can ask your AI assistant:

- "List asset collections in TQ Data Foundation"
- "How many triples are in the Geo taxonomy in Data Foundation?"
- "List people in the Kennedys graph in Data Foundation"
- "Count the number of instances for each class in the Northwind collection in Data Foundation"


Onboarding
==========

.. note::
   This feature is currently experimental.

The MCP server is an experimental feature that must be enabled by TopQuadrant
for a Data Foundation environment. Administrators should contact TopQuadrant
Support to have the MCP server enabled.


Server URL
==========

Once the MCP server has been enabled for your environment, you receive its URL
and can connect your AI application. For a Data Foundation instance reached at
``https://{hostname}/edg``, the MCP server URL is typically
``https://mcp.{hostname}/mcp``. If you have not received your MCP server URL,
contact your administrator or TopQuadrant Support.


Client Compatibility
====================

The MCP server requires a client application that supports remote MCP over
HTTPS with OAuth 2.1, PKCE, and Dynamic Client Registration (DCR).


Connecting an AI Application
============================

The exact steps for adding a remote MCP server depend on the AI application.
Refer to the application's own documentation for the most up-to-date
instructions, and use your MCP server URL. Brief pointers for several common
applications follow.

Claude Code
-----------

Add the MCP server with the ``claude mcp add`` command, using the
``--transport http`` option and the server URL, for example::

   claude mcp add --transport http data-foundation <your-MCP-server-URL>

Here ``data-foundation`` is a name you choose for the connection. See
`Connect to MCP servers (Claude Code) <https://code.claude.com/docs/en/mcp-quickstart#connect-to-mcp-servers>`_.

Claude.ai, Claude Desktop and Claude Cowork
-------------------------------------------

Remote MCP servers are added as custom connectors from the application's
settings. The exact steps depend on your Claude plan:

- On **Team and Enterprise** plans, an organization owner adds the connector;
  members then turn it on for their own account.
- On **Max and Pro** plans, add the connector directly from your own settings
  under **Customize > Connectors**.

See
`Get started with custom connectors using remote MCP <https://support.claude.com/en/articles/11175166-getting-started-with-custom-connectors-using-remote-mcp>`_.

OpenAI Codex
------------

Add the MCP server with the ``codex mcp add`` command, specifying the server
URL as a streamable HTTP server. See
`Codex MCP <https://developers.openai.com/codex/mcp/>`_.

VS Code
-------

Add the server through **MCP: Add Server** in the Command Palette, choosing the
HTTP server type and entering the server URL. See
`Use MCP servers in VS Code <https://code.visualstudio.com/docs/copilot/customization/mcp-servers>`_.


Authorization
=============

After you connect to the MCP server in your AI application, you are asked to
authorize access to Data Foundation. An SSO authorization page opens in your
browser. After you approve the request, the AI application is able to connect
to Data Foundation on your behalf.

If the authorization page does not open automatically, check that your browser
is not blocking pop-ups, or copy the authorization URL from the AI application
and open it manually.

Once authorized, ask your AI assistant to list your asset collections in Data
Foundation to confirm that the connection is working.