Model Context Protocol (MCP) server

The ClearPoint MCP server lets an AI client operate on your ClearPoint data. The server gives the client a selected group of tools. The client can find data in a scorecard, answer questions about performance, get elements, write measure data, and change statuses. All tools use the permissions of the ClearPoint user who signs in.

Model Context Protocol is an open standard. It connects AI clients to other systems. Any client with MCP support can connect, for example Claude, ChatGPT, or Microsoft Copilot. For more data, refer to modelcontextprotocol.io.

The address of the server

https://mcp.clearpointstrategy.com/mcp

The server has a second address for read operations only. It gives the nine tools that read data. Refer to The read-only address.

https://mcp.clearpointstrategy.com/mcp/read

Before you start

You must have these three items:

• An organization with the Enterprise plan.
• A ClearPoint user account, or a pair of ClearPoint API keys. The tools use the permissions of that account.
• An AI client with support for a remote MCP server with Streamable HTTP.

The server has two authentication methods. An AI client that a person operates uses OAuth 2.0. An integration that operates without a person uses API keys. Refer to Authentication.

How to connect your client

1. Open the settings for MCP servers, connectors, or custom integrations in your client.
2. Add a remote MCP server. Set the transport to Streamable HTTP.
3. Enter the full address of the server with the /mcp part: https://mcp.clearpointstrategy.com/mcp
4. Start the sign-in procedure. Enter your ClearPoint user name and password.
5. Refresh the tool list in the client.

Step 5 is important. The server makes the tools for each connection. The tools include the custom fields, the element names, and the configuration of your account. If the client does not refresh the tool list, it does not have all the data for your account.

📘

Each user connects with a personal account

Each person connects with a personal ClearPoint account. There is no shared connection to set up. An administrator does not send a credential to the users.

JSON configuration

Some clients use a JSON file for the configuration. Use this example as a start. Then change the field names to the format of your client.

{
  "mcpServers": {
    "clearpoint": {
      "transport": "streamable-http",
      "url": "https://mcp.clearpointstrategy.com/mcp"
    }
  }
}

The read-only address

The address https://mcp.clearpointstrategy.com/mcp/read gives only the nine tools that read data. The other 46 tools are not available at this address. An AI client on this address cannot make a change to your ClearPoint data.

Use this address in these conditions:

• A team must examine ClearPoint data in an AI client, but must not change it.
• Your security policy does not let an AI client write data.
• You do a test of the connection before you give the full server to your users.

To use this address, do the same procedure as above. Use https://mcp.clearpointstrategy.com/mcp/read in place of https://mcp.clearpointstrategy.com/mcp. The authentication is the same for both addresses.

How the tools relate to the data

Three rules tell you about most of the tools. The same rules apply to the REST API.

Use list to find an ID. Most tools need an ID, not a name. Use list to find the IDs for scorecards, periods, period groups, statuses, users, and tags.

edit_ tools change the configuration. update_ tools change the reporting data. To change the name or the owner of a measure, use edit_measure. To record the result and the notes for this quarter, use update_measure_status. The two tools are different. Do not use one tool in place of the other.

Custom fields go in customFields. Use the ID of the field as the key. The format is a number or customNNN.

The tools

The server has 55 tools at /mcp and nine tools at /mcp/read. This page shows all of them. The tool list in your client is correct for your account, because the server makes the tools for each connection.

Each tool has an annotation. The client uses the annotation to decide when it asks for your approval.

The edit_ tools and the update_ tools have the Destructive annotation because they write over values. They do not remove records.

Tools that read data

Tools that make and change items

Each element type has a create_ tool and an edit_ tool.

The create_ tools have the Write annotation. The edit_ tools have the Destructive annotation.

Three more tools operate on all element types.

Tools that change a status

These tools write the reporting data for a period. This data changes in each cycle.

Tools for links

Permissions and safety

The server does not have its own permissions. Each tool call operates as the ClearPoint user who signs in. The ClearPoint API applies the account scope, the permission level, the data checks, the rules, and the soft delete. These controls are the same as the controls in the application.

The results are:

• A user with Browser permission cannot write data. The request of the client does not change this condition.
• A user sees only the scorecards that the account can access.
• A delete operation is a soft delete. The delete tool removes the element from the application, but ClearPoint keeps the record.
• ClearPoint records the name of the user with each change.
• An API key pair belongs to one ClearPoint user. The same permissions apply to it.

Do these three things when you give the server to your organization:

• Keep the approval messages of the client set to on. The client uses the annotations in the tables above. It then asks a person for approval before a write operation or a destructive operation.
• Use the ClearPoint permissions as the control. If a team must only read data, set the ClearPoint permission of that team to Browser. Do not use the configuration of the client as the control.
• Give the read-only address to teams that must not write data. The address /mcp/read does not have the tools that write data. This control is separate from the permissions of the user.

Authentication

The server has two authentication methods:

• OAuth 2.0 for an AI client that a person operates.
• API keys for an integration that operates without a person.

Both methods give access to /mcp and to /mcp/read.

OAuth 2.0 for interactive clients

The server uses OAuth 2.0 with the authorization code grant and PKCE. It also has support for dynamic client registration. Most clients connect with the address of the server only. You do not give more values.

If your client needs the OAuth endpoints, it gets them from this discovery address:

https://mcp.clearpointstrategy.com/.well-known/oauth-authorization-server

Use this discovery address in your client. Do not write the endpoints into your configuration. Your client then gets the correct endpoints, also after a change to the server.

There is no client credentials grant. For an integration that operates without a person, use API keys.

API keys for integrations without a person

Use ClearPoint API keys for a scheduled integration or for a server-to-server integration. This method does not use an OAuth procedure and does not need a browser.

Send the keys in two headers with each request to POST /mcp or to POST /mcp/read:

AccessKey: <your access key>
SecretKey: <your secret key>

These keys are the same keys as the keys for the ClearPoint REST API. One pair gives access to both. Make them in the ClearPoint application.

A key pair belongs to one ClearPoint user. The tools get the permissions of that user.

🚧

Make a user account for the integration

Do not use the account of a person for an integration. If that person leaves your organization or gets a different role, the integration stops. Make a ClearPoint user account for the integration and give it the minimum permissions that it needs.

Keep the keys in a safe location. Do not put them in your software code.

The MCP protocol version

The client and the server agree on the MCP protocol version in the initialize step of each session. Do not set a fixed version in your client.

Metadata addresses

Most clients get this data without your help.

Limits

The server gives these values in its discovery metadata:

ClearPoint records the use of the server. Make your integration ready for a limit: read the status code of each response, and send the request again later if the status is 429.

How to test the connection

An MCP inspector shows the tool list and sends tool calls from a browser. This is the quickest method to make sure that you have access. It also shows the correct fields for each tool.

Open the inspector

Enter your ClearPoint user name and password. Then use a read-only tool, for example list. Do not use a tool that writes data until the connection is correct.

Problems and solutions

Support

For problems with access or with a connection, send a message to [email protected].