Skip to main content

​
What is MCP?

Model Context Protocol (MCP) lets AI assistants like Claude call Govly tools on your behalf. Govly’s MCP server lives at https://app.govly.com/api/mcp and acts as you: it only returns data your Govly account is allowed to see, scoped the same way as the web app. More tools are being added regularly. To start, connected clients can list the workspaces you have open in Govly.

​
Choose a connection method

There are two ways to connect:
  • OAuth — recommended whenever your client supports it. You sign in through Govly once and the client handles the rest. No tokens to copy or rotate.
  • Personal API key — for clients that only accept a static bearer token, or when you want a stable credential you can paste into a config file.
If you’re not sure which your client supports, try OAuth first.

​
Option 1: Connect with OAuth

When you add Govly’s MCP URL to a client that supports OAuth, the client redirects you through Govly sign-in and stores the connection for you.
  1. In your AI client, add a custom MCP connector.
  2. Enter the server URL: https://app.govly.com/api/mcp.
  3. The client opens a browser tab and sends you through Govly sign-in.
  4. Approve access on the consent screen.
  5. Ask the assistant something like “What workspaces do I have in Govly?” to confirm the connection.
A few things to know:
  • Your Govly account must already exist. The OAuth flow does not create new users.
  • You can revoke access anytime in Govly under Settings → API → Connected Apps.

​
Option 2: Connect with a personal API key

For clients that take a static bearer token, create a personal API key in Govly and add it to your client’s MCP config.

​
Step 1: Create a personal API key

  1. Go to Settings → API → API Keys in Govly.
  2. Under Personal API Keys, click New key.
  3. Name it after the client you’ll use it with.
  4. Copy the gk_... token immediately. It is only shown once.
You can keep up to 2 active personal keys at a time. Revoke a key from the same page if it leaks or you stop using it.

​
Step 2: Configure your client

Most MCP clients accept a config block like this: 
{
  "mcpServers": {
    "govly": {
      "url": "https://app.govly.com/api/mcp",
      "headers": {
        "Authorization": "Bearer gk_<your_personal_api_key>"
      }
    }
  }
}
The exact location of this config varies by client. Check your client’s MCP setup docs.

​
Step 3: Verify the connection

curl -X POST https://app.govly.com/api/mcp \
  -H "Authorization: Bearer gk_<your_personal_api_key>" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'
You should get back a JSON-RPC response listing available tools, including list_workspaces.

​
Shared or service accounts

If your team wants a shared agent or service account to connect to MCP, email support@govly.com. Include:
  • The display name and email you’d like for the service account.
  • A short description of what it will be used for.
Personal API keys are tied to a specific person and should not be shared across users or systems.

​
Using MCP across multiple Govly organizations

This only applies if you belong to more than one Govly organization.

​
Personal API key

When you connect to Govly via personal API keys in multiple organizations, create and use keys from each organization.

​
OAuth

When you connect to Govly via OAuth, that connection is tied to the organization you were viewing when you signed in. Switching organizations inside Govly afterward does not change what the connection can see. If you need MCP to work for a second organization, add a separate Govly connector from that organization.

​
Managing your connections

  • Personal API keys — manage under Settings → API → API Keys.
  • OAuth-connected apps — manage under Settings → API → Connected Apps.
Revoking an OAuth grant immediately invalidates that connection.

​
Troubleshooting

  • 401 Unauthorized — Your API key is wrong, revoked, or expired. Create a new key and update your client config.
  • 401 “Grant has been revoked” — Your OAuth grant was revoked. Reconnect from your client.
  • A tool you expected is missing — Some tools require Enterprise API access. Contact your Govly admin if you think you should have access.
Still stuck? Email support@govly.com with the client you’re using and any error messages you’re seeing.