> ## Documentation Index
> Fetch the complete documentation index at: https://docs.govly.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP for Developers

> Connect APIs and developer tools to Govly MCP

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](/enterprise/integrations/mcp/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:

```text theme={null}
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

<Steps>
  <Step title="Add a remote MCP server">
    In your client, add a remote MCP server named `Govly` with the URL `https://app.govly.com/api/mcp`.
  </Step>

  <Step title="Sign in to Govly">
    Follow the browser prompt and sign in to your existing Govly account. Govly's OAuth flow does not create new users.
  </Step>

  <Step title="Approve access">
    Review the authorization request and approve the connection.
  </Step>

  <Step title="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?”
  </Step>
</Steps>

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

<Warning>
  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.
</Warning>

### Create a personal API key

<Steps>
  <Step title="Open API settings">
    In Govly, go to **Settings → API → API Keys**.
  </Step>

  <Step title="Create a personal key">
    Under **Personal API Keys**, select **New key** and name it after the client that will use it.
  </Step>

  <Step title="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.
  </Step>
</Steps>

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:

```json theme={null}
{
  "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:

1. Add a remote MCP server named `govly`.
2. Use `https://app.govly.com/api/mcp` as the server URL.
3. Use your personal Govly API key as the server authorization token.
4. Require approval for tool calls while you test the integration.
5. 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:

```bash theme={null}
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.

<Steps>
  <Step title="Create the agent">
    An organization admin goes to **Settings → API → Agent Accounts** and creates an agent, naming it after the integration it will run.
  </Step>

  <Step title="Create a key">
    Select **New key** on that agent, then copy the `gk_...` token.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Connect your client">
    Use the same configuration as a personal key, with the agent's token as the bearer value.
  </Step>
</Steps>

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.

<Note>
  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.
</Note>

### 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](/api-reference/tools-v1) 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](mailto:support@govly.com)** with the client you're using and any error messages you're seeing.