Connecting an AI Client
=======================

.. important::
    **Beta Feature** — MCP Server (AI Access) is currently in beta and is being rolled out to
    databases over the coming weeks. It may not be available in your database yet, and the
    details on this page may still change during the beta. See :doc:`index`.

Once an administrator has enabled the MCP server and granted you the ``McpAccess`` role, you
connect your AI client to TouchPoint with two pieces of information: your church's MCP endpoint
URL and a Personal Access Token issued to your own TouchPoint user account.

The endpoint URL is::

    https://mychurch.tpsdb.com/api/mcp

Replace ``mychurch`` with your church's TouchPoint subdomain — the same one you use to log in.
It is also displayed at the top of the `MCP Server (AI Access)` admin page.

Getting a Personal Access Token
-------------------------------
Click your name in the top bar of TouchPoint and choose **Manage Personal Access Tokens**, then
click `Create New Token`. The full token value is shown only once, at the moment you create it,
so copy it before you close the banner.

.. important::
    A Personal Access Token acts as you. Anyone who has it can do anything through MCP (and
    through the Rest API) that your TouchPoint roles allow. Do not share it, do not paste it into
    a chat window, and revoke it if it is ever exposed.

.. seealso::
    :doc:`../API/PersonalAccessTokens`

Configuring Your Client
-----------------------
MCP clients keep their server list in a JSON configuration file. TouchPoint uses the standard
Streamable HTTP transport, so any MCP client that supports a remote HTTP server with custom
headers will work. The token is sent in an ``Authorization`` header using the ``PAT`` scheme.

**Claude Desktop**

Edit ``claude_desktop_config.json`` (`Settings > Developer > Edit Config`) and add a
``touchpoint`` entry::

    {
      "mcpServers": {
        "touchpoint": {
          "url": "https://mychurch.tpsdb.com/api/mcp",
          "headers": {
            "Authorization": "PAT 37402a24-c96e-4575-b063-fb41fbb28651"
          }
        }
      }
    }

**Cursor**

Edit ``~/.cursor/mcp.json`` — the format is the same::

    {
      "mcpServers": {
        "touchpoint": {
          "url": "https://mychurch.tpsdb.com/api/mcp",
          "headers": {
            "Authorization": "PAT 37402a24-c96e-4575-b063-fb41fbb28651"
          }
        }
      }
    }

Substitute your own subdomain and token in both examples, and restart the client after editing
the file so it picks up the new server.

Verifying the Connection
------------------------
Ask the agent to run the ``who_am_i`` tool, or simply ask it *"who am I in TouchPoint?"*. A
working connection returns your TouchPoint user name, the person you are attached to, and the
roles you hold — which is also the quickest way to confirm whether you have the de-masking roles
and whether write actions are enabled for your church.

Troubleshooting
---------------
The MCP server returns a specific message when it refuses a connection. The most common ones:

*Missing Authorization header* or *Unsupported Authorization scheme*
    The client is not sending the token, or is sending it as something other than
    ``Authorization: PAT <token>``. Check for a typo in the header name or a missing ``PAT``
    prefix — the word ``PAT``, a single space, then the token.

*PAT token is not recognized or has been revoked*
    The token has been revoked, has passed its expiration date, or was mistyped. Create a new one
    and update your configuration.

*The resolved user does not have AI access enabled*
    Your TouchPoint user does not hold the ``McpAccess`` role. Ask an administrator to add it from
    your user account's `AI Features` roles.

*MCP server is not enabled for this TouchPoint instance*
    An administrator has not enabled the MCP server for your church, or has disabled it. See
    :doc:`ConfiguringMcpServer`.

Fields coming back as ``[redacted]``
    You do not hold ``McpViewContact`` (phone, email, address) or ``McpViewDemographics`` (birth
    date, age, gender, marital status). This is expected behavior, not an error; an administrator
    can grant those roles.

A write tool refused to run
    Either your church has `Allow Write Actions` turned off, or your TouchPoint roles do not
    permit that specific change. The agent will report which.