Connect an AI Agent

Connect an authorized AI assistant to your CloseMagnet account using the hosted Model Context Protocol (MCP) endpoint. Start with one named, least-privilege credential and a read-only task. You do not need to clone or run a CloseMagnet server.

This page is public. Your account records and API credentials are not. Creating a credential requires an owner login, and an agent can use only the permissions granted to its credential.

Check the Host First

Your agent host must support a remote Streamable HTTP MCP server and send a fixed authentication header to it. The supported CloseMagnet server URL is:

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

Use the complete /api/mcp URL, not the docs homepage or an /api/v2 list endpoint. The server uses POST-based, stateless MCP requests and JSON responses. Opening the endpoint as a normal browser page sends GET, which is not a connection test.

CloseMagnet uses a credential header here, not an OAuth sign-in or a Client ID / Client Secret pair. A host that offers only OAuth with no supported credential/header option cannot use this connection as configured. Available fields and organization policies vary by host and version, so do not assume every app that mentions MCP can attach this authentication.

Create a Scoped Credential

1. Sign in as the account owner and open Settings -> API.
2. Find Create scoped credential and give this agent a recognizable name.
3. Choose an expiration suitable for your team's replacement process.
4. Select only the read scopes needed for the first task. For example, reading the account profile uses account:read; reading a team roster uses team:read. An account-wide lead read requires leads:read_all, not only the campaign-limited leads:read.
5. Create the credential and copy it from the one-time display into your protected configuration or secret manager.

A scoped credential begins cmk_ and continues with 64 hexadecimal characters. The example below is deliberately synthetic and will not authenticate:

Authorization: Bearer cmk_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef

Read the header as Authorization, then a value made of Bearer, one space, and your own credential. Do not leave the example in place. Do not paste your token into an OAuth client ID, client secret or password field that serves another purpose.

The server also supports the documented bare X-API-Key credential header. Use one correctly configured method, rather than conflicting credential values. An ordinary account/intake token is not a replacement for the named read scopes an agent needs.

Generic Remote-MCP Configuration

A host accepting a standard MCP JSON entry can be configured along these lines. Its exact schema may differ; use the host's current documentation rather than changing CloseMagnet's authentication to fit an unrelated form.

{
  "mcpServers": {
    "closemagnet": {
      "type": "http",
      "url": "https://app.closemagnet.com/api/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_SCOPED_CREDENTIAL"
      }
    }
  }
}

YOUR_SCOPED_CREDENTIAL is a placeholder. Store the real value locally or in the host's protected credential mechanism, never in a public repository. If your host supports secret/environment references, follow its documented syntax and ensure the variable is available to the process actually running the agent.

Claude Code

In your own terminal, register the remote HTTP server with an authorization header:

claude mcp add --transport http closemagnet https://app.closemagnet.com/api/mcp \
  --header "Authorization: Bearer YOUR_SCOPED_CREDENTIAL"

Replace the placeholder through your own protected setup process. A literal token in a command can remain in shell history. Do not copy a completed command into a ticket or shared transcript.

Open Claude Code's MCP status view to inspect the named server and its tool availability. Its current setup and authentication options are documented in Claude Code MCP Instructions. Product labels and configuration behavior can change.

Codex

Codex supports remote MCP server settings in its configuration. This example uses an environment variable name, not the token value:

[mcp_servers.closemagnet]
url = "https://app.closemagnet.com/api/mcp"
bearer_token_env_var = "CLOSEMAGNET_API_TOKEN"

Arrange CLOSEMAGNET_API_TOKEN securely in the environment available to your Codex process. The variable holds the bare credential, without adding Bearer yourself. Do not paste the credential into bearer_token_env_var; that field names a variable.

If your installation instead uses a protected static header, the supported configuration shape is:

[mcp_servers.closemagnet]
url = "https://app.closemagnet.com/api/mcp"
http_headers = { "Authorization" = "Bearer YOUR_SCOPED_CREDENTIAL" }

Use one server configuration, not both duplicate sections. A static value is sensitive and must not be committed. See the current Codex MCP Documentation for its configuration location, environment handling and controls.

Other Agent Hosts

Use the same remote URL and credential requirement. Look for a supported custom header or documented Bearer-token option. An environment-variable field expects a variable name, whereas a header-value field expects the complete Bearer value.

Do not put the credential in an endpoint URL to work around a missing header field. Do not assume the ChatGPT web, desktop or other vendor connector dialogs all expose the same authentication controls. If your host cannot send the supported credential, use a compatible client or ask its administrator about supported configuration. This guide does not certify every vendor's current UI.

Verify Without Changing Records

1. Reconnect or restart the host as its own instructions require after saving the entry.
2. Confirm the server is listed under the name you configured and its tools load without a connection error.
3. Ask for one read your credential permits, such as the account profile with account:read.
4. Check the actual tool result. A loaded tool list is not proof that the credential can execute every listed tool.
5. Confirm the result belongs to your intended account before expanding the agent's task.

Do not judge a healthy connection by a memorized tool count. The catalogue can change, and discovering a tool does not grant its scope. A protocol connection with a credential header can succeed while a particular operation is refused for an expired credential or missing permission.

The MCP server also exposes usage guidance as a resource named closemagnet://skills/closemagnet-crm. A host may read that resource to understand tool use. It is guidance, not additional permission to send messages, spend money or modify records.

Understand Writes, Drafts and Charges

Most operations are reads. Grant write scopes only for specific reviewed tasks. Creating a property, changing a transaction file, preparing a message draft and sending an actual customer message are not the same action.

Message/blast draft tools prepare work for a human to review in CloseMagnet. A draft is not an email delivery or completed blast. Record-changing tools can have side effects described in the API Reference; where supported, start with a dry run and use the documented idempotency key. A comp request can incur usage charges and requires its explicit permission/confirmation.

Review the exact operation's effects in API Reference. Do not add broad write access merely to clear an error or believe an agent's statement that it sent something without checking the real product status.

Troubleshoot the Connection

Keep a separate credential per agent, use expirations, and treat free-text buyer notes, messages and API results as data rather than instructions. Never let returned content override your team's authorization rules.