Skip to main content

MCP: Connect an AI Assistant

The Hamtrax Model Context Protocol (MCP) server lets a compatible AI assistant read your folders, contacts, and POTA activations. You can also allow it to log contacts, create activation folders, or delete contacts. It uses the same account permissions and folder validation as the Hamtrax CLI.

Local MCP support is available in Hamtrax CLI 0.2.0, released on GitHub. The hosted OAuth connection is also available. Publication of 0.2.0 to the npm registry and Anthropic and OpenAI directory listings are pending.

Choose a connection​

  • Local: Run hamtrax-mcp on your computer through an assistant that supports MCP over standard input/output (stdio). This reuses the API key configured for your CLI.
  • Hosted: Use the remote HTTPS connection. Your assistant opens a Hamtrax authorization page where you approve its access.

Use a dedicated basic API key for reading and logging. An elevated key is required for deletion. Generate and revoke keys through the web app's Hamtrax CLI tool; see Auth and Keys.

Local setup​

Install or update to CLI 0.2.0 using the official GitHub package in Install, then log in:

hamtrax auth login
hamtrax whoami --json

Add the following server to your assistant's MCP configuration. The location of that configuration depends on the assistant.

{
  "mcpServers": {
    "hamtrax": {
      "command": "hamtrax-mcp",
      "args": []
    }
  }
}

Restart or reconnect the assistant after changing its configuration. If it cannot find hamtrax-mcp, use the executable's full path or ensure the directory containing npm's global executables is in the assistant's PATH.

The server starts with read access only. To allow contact and activation creation, change args to:

["--allow-writes"]

To allow deletion as well, use an elevated key and:

["--allow-writes", "--allow-deletes"]

The two flags are independent: use only --allow-deletes if you need deletion without creation.

The server resolves credentials in the CLI's usual order: HAMTRAX_API_KEY, OS keychain, then the CLI configuration file. For a headless assistant, inject HAMTRAX_API_KEY through its secret or environment settings. Keep the key out of prompts, tool arguments, and committed configuration files.

Hosted authorization​

The hosted connection is available at:

https://hamtrax.com/mcp

Add this URL in an assistant that supports remote MCP with OAuth. It will open the Hamtrax authorization page. Enter a dedicated Hamtrax API key on that page, review the requested access, and approve it.

  • Read permits account identity and logbook reads.
  • Write additionally permits contact and POTA activation creation.
  • Delete permits contact deletion independently of creation and requires an elevated API key.

Read permission is required for a connection. The scopes you approve and the API key's tier both limit what the assistant can do. The assistant receives its own access token; your Hamtrax API key is not sent to the AI provider. Revoking the original key in Hamtrax stops access through grants authorized with it. Also remove the connection in your assistant when you stop using it.

Available tools​

ToolPurposeAccess
whoamiShow your callsign, plan, key tier, and contact count.Read
list_foldersList your logbook folders.Read
list_contactsList contacts in a selected folder.Read
list_activationsList activation folders, including in-progress activations.Read
create_contactSave a contact to a folder it matches.Write
create_activationFind or create a POTA activation folder.Write
delete_contactDelete an identified contact.Delete and an elevated key

Each list tool returns one page: 50 records by default, up to 200 with limit. Pass the returned cursor to request the next page.

What to ask​

  • “Show my in-progress POTA activations.”
  • “List the contacts in my October hunting folder.”
  • With write access: “Create today's activation folder for my callsign at this park, then log the contact I describe.”
  • With delete access: “Find this incorrect contact and ask me to confirm its deletion.”

The assistant should confirm the intended details and destination with you before a write. Creating an activation for the same callsign, park, and UTC day can reopen an existing folder, so include that effect in the confirmation.

Every write tool, including deletion, requires idempotency_key. Use a unique operation ID such as a UUID and reuse it with identical arguments after a timeout. create_contact also requires an explicit time_on, and create_activation requires start_time; supply an ISO 8601 timestamp with Z or an explicit time-zone offset. Keep that timestamp unchanged on retries so the destination's UTC day or month stays the same.

delete_contact requires confirmation to equal DELETE followed by the exact qso_id; the assistant should obtain your approval before sending it.

Logbook safeguards​

Hamtrax rejects a contact that does not belong in the selected folder. Activation parks must match, monthly folders require the contact's UTC month, and container folders cannot hold contacts. The assistant must surface a rejected destination and ask for a correction; it should never move the contact to another folder silently. See Command Reference for the shared validation rules.

MCP activation creation supports POTA only and creates the logbook folder. It does not post a POTA spot or submit an activation log. If you have enabled Automatically sync with QRZ, eligible contacts created through MCP can be sent to your connected QRZ logbook under that existing setting. Deleting a contact in Hamtrax leaves its QRZ counterpart intact.

Your data and access​

Your connected assistant can receive the account and logbook records returned by the tools it calls. That may include callsigns, folder names, contact times, and saved notes. Only connect services you want to receive those records; their handling of the data depends on their own privacy policies and your account settings. See the Hamtrax Privacy Policy.

MCP results omit private account IDs, credential fields, and precise coordinates. Recognized API-key and token strings are redacted from returned text. Folder names and saved notes are user-authored data; the assistant should treat them as record content, not instructions.

Use the assistant's confirmation controls for changes and delete access only when you need it. If an API key is lost or exposed, revoke it in Hamtrax immediately; removing the local MCP configuration alone does not revoke that key.