MCP for Developers

Use this guide to connect an AI provider API, command-line tool, or other MCP client to Govly. To use Govly in the hosted Claude app, follow Connect to Claude instead.

Before you start

You need:

A Govly account with a paid seat. Enterprise API access is not required to connect.
A client that supports remote HTTP MCP servers.
A Govly API key if your client only accepts a static bearer token — either a personal key or an agent account key, depending on who is driving the connection.

Use Govly’s remote MCP server URL:

https://app.govly.com/api/mcp

Choose an authentication method

Start with one question: is this connection an integration, or is it you?

You are connecting…	Use	Why
Yourself, in a client that supports OAuth	OAuth	Actions are attributed to you and the connection is revocable in one place.
Yourself, in a client that only takes a bearer token	Personal API key	Still your identity — just no OAuth flow available.
An integration that runs on a schedule or outlives whoever set it up	Agent account key	The integration owns its own identity instead of borrowing a person’s.

The deciding question for that last row: if the person who set this up left tomorrow, should it keep running? If yes, use an agent account. A personal key stops working when that person is deactivated, which takes the integration down with them.

Connect with OAuth

Add a remote MCP server

In your client, add a remote MCP server named Govly with the URL https://app.govly.com/api/mcp.

Follow the browser prompt and sign in to your existing Govly account. Govly’s OAuth flow does not create new users.

Approve access

Review the authorization request and approve the connection.

Test the connection

Ask the client to list its Govly tools or try a small request such as, “What workspaces do I have in Govly?”

Clients that support OAuth discovery do not require a separate OAuth client ID or client secret. Manage OAuth connections under Govly Settings → API → Connected Apps.

Connect with a personal API key

A personal API key lets an external client access Govly as you. Store it in a secret manager or environment variable, never commit it to source control, and revoke it immediately if it is exposed.

Create a personal API key

Open API settings

In Govly, go to Settings → API → API Keys.

Create a personal key

Under Personal API Keys, select New key and name it after the client that will use it.

Copy and store the key

Copy the gk_... token into a secret manager or environment variable. The token stays visible on this page, so treat access to your API settings as access to the key itself.

You can keep up to two active personal keys at a time. Personal keys are tied to a specific user and must not be shared across users or systems.

Configure your client

Most MCP clients accept a configuration block like this:

{
  "mcpServers": {
    "govly": {
      "url": "https://app.govly.com/api/mcp",
      "headers": {
        "Authorization": "Bearer gk_<your_personal_api_key>"
      }
    }
  }
}

The exact configuration format and location vary by client. Use your client’s secure secret or authorization-token setting when available instead of saving the key directly in a configuration file.

Connect through an AI provider API

When an AI provider API supports remote MCP servers:

Add a remote MCP server named govly.
Use https://app.govly.com/api/mcp as the server URL.
Use your personal Govly API key as the server authorization token.
Require approval for tool calls while you test the integration.
Start with a low-risk request, such as listing Govly tools or running one opportunity search.

Provider request formats differ, so use the provider’s current remote MCP documentation for exact field names and approval settings.

Verify the connection

Send a JSON-RPC tools/list request with your personal key:

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"}'

A successful response lists the Govly tools available to your account, including search_opportunities, search_awards, search_contacts, search_places, list_places, document_read, document_download, and list_workspaces.

Connect with an agent account key

An agent account is a non-human identity in your organization. It holds its own API keys, so a durable integration does not depend on an employee’s account and does not share an organization-wide credential that belongs to nobody. Agent accounts are not people. They have no mailbox, cannot sign in, do not receive notifications or digests, and cannot be shared with or @-mentioned. They act only through their API keys.

Create the agent

An organization admin goes to Settings → API → Agent Accounts and creates an agent, naming it after the integration it will run.

Create a key

Select New key on that agent, then copy the gk_... token.

Store the key

Put it in a secret manager or environment variable, never in source control. The token stays visible on the Agent Accounts page, so anyone who can administer your organization’s API settings can read it. Revoke a key if you suspect it has been exposed — revocation is immediate and permanent.

Connect your client

Use the same configuration as a personal key, with the agent’s token as the bearer value.

Each organization can hold up to five active agent accounts, and each agent can hold two keys so a key can be replaced without downtime.

Agent accounts cannot use OAuth, because they cannot sign in. That also means they cannot be used with the Govly connector in the hosted Claude app, which authorizes through a browser sign-in. Use an agent key from a client that accepts a bearer token — a command-line tool, an AI provider API, or your own scheduled job.

Developing against an agent account

Use the agent’s key while you build the integration, not your own. You will be testing with the identity that will actually run in production, so permission and subscription differences surface during development rather than after deploy.

Deciding what to build on

MCP is worth its complexity when a model needs to choose which tools to call. If your code already knows which calls to make — fetch new matches, filter by NAICS, write to your CRM — the Tools API is simpler, cheaper, and easier to test. An agent account key works on either surface.

Multiple Govly organizations

OAuth connections, personal API keys, and agent accounts are all scoped to the Govly organization where they were authorized or created. To connect another organization, authorize a separate OAuth connection while viewing that organization, or create a separate key from it.

Manage keys

Key-based connections do not appear under Connected Apps.

Personal keys — Govly Settings → API → API Keys.
Agent account keys — Govly Settings → API → Agent Accounts, on the agent that owns them.

After rotating a key, update every client that used the previous value. Revoking a key is permanent; issue a new one rather than expecting to restore it. Archiving an agent revokes its keys and stops it authenticating immediately, while leaving its past activity attributed to it.

Troubleshooting

Issue	What to check
`401 Unauthorized`	Confirm the key is correct, active, and sent as a bearer token. If it belongs to an agent, confirm the agent has not been archived.
`401 Grant has been revoked`	Reconnect through your client’s OAuth flow.
`403 Paid Govly seat required`	An agent inherits its organization’s subscription rather than holding a seat, so check the organization’s plan.
A tool you expected is missing	Some tools require Enterprise API access or another Govly subscription. Contact your Govly administrator if you believe you should have access.
The connection is missing from Connected Apps	Key-based connections are managed under API Keys or Agent Accounts instead.
An agent key fails in the hosted Claude app	That connector authorizes through browser sign-in, which agents cannot do. Use a client that accepts a bearer token.

Still stuck? Email support@govly.com with the client you’re using and any error messages you’re seeing.

Getting Started

Integrations

Enterprise

Before you start

Choose an authentication method

Connect with OAuth

Connect with a personal API key

Create a personal API key

Configure your client

Connect through an AI provider API

Verify the connection

Connect with an agent account key

Developing against an agent account

Deciding what to build on

Multiple Govly organizations

Manage keys

Troubleshooting

​Before you start

​Choose an authentication method

​Connect with OAuth

​Connect with a personal API key

​Create a personal API key

​Configure your client

​Connect through an AI provider API

​Verify the connection

​Connect with an agent account key

​Developing against an agent account

​Deciding what to build on

​Multiple Govly organizations

​Manage keys

​Troubleshooting

Before you start

Choose an authentication method

Connect with OAuth

Connect with a personal API key

Create a personal API key

Configure your client

Connect through an AI provider API

Verify the connection

Connect with an agent account key

Developing against an agent account

Deciding what to build on

Multiple Govly organizations

Manage keys

Troubleshooting