Connect AI agents

Connect an agent to review SEO, investigate a supported opportunity or implement a mission. You do not need a repository just to read findings. Start by adding your public website in the app, then open Agents from the workspace connection link. Choose the client and the access it needs. Serpkin uses the same authenticated MCP endpoint for every client; client names change the setup instructions, not the evidence behind recommendations.

#Choose access

Create a separate key for each role. Research and full-access keys can have an additional monthly credit ceiling. Queued and running research reserves credits against it; settled work counts its charged credits. The ceiling resets with the UTC calendar month and never adds to your workspace allowance. A zero ceiling prevents credited research. Blank means there is no extra key ceiling. Existing keys and CLI device-login keys retain full access unless the owner changes them.

Site-level schedules and automatic topic research are separate workspace activity, not jobs started by a particular key. A key ceiling does not cap that activity, model spending or the number of free reads. Review the site's automatic-research setting separately. Changing or revoking a key affects new requests; already accepted jobs continue. The owner can edit access and ceilings in Agents without sharing credentials with the agent.

#Hermes

Merge the following into the active Hermes profile's configuration, normally ~/.hermes/config.yaml. Preserve existing servers. Put the real key in the profile's private environment or its process environment. Hermes supports environment references in headers; Serpkin does not require an AI-provider key for the connection.

mcp_servers:
  serpkin:
    url: "https://serpkin.com/api/mcp"
    headers:
      Authorization: "Bearer ${SERPKIN_API_KEY}"

Reload MCP or restart the Hermes session, then ask it to call serpkin_get_workspace. A valid authenticated response is the connection check. A configuration entry alone is not proof that the key resolved or that the server is reachable. For CLI-assisted configuration, use npx serpkin --connect-only --agent hermes. The CLI writes a new configuration file but leaves a nonempty existing file untouched and prints the entry to merge.

#Grok Bot

In Grok Bot's app connections, add a custom MCP server using https://serpkin.com/api/mcp. Supply a Serpkin key through protected bearer-header settings where the current connector supports them. Do not paste the key into a Bot conversation. The public Grok Bot documentation describes custom MCP connections, but its live static-key sign-in flow has not been exercised here. This is a manual connection path, not a listed marketplace plugin or a claim of native certification.

Grok Bot runs on its own computer. A localhost Serpkin URL on your laptop will not refer to that server from the Bot. Use a reachable HTTPS deployment and honor your team's connection policy. Grok Build is a separate coding product with its own MCP configuration; do not substitute its terminal commands for the Bot's connector settings.

#Other MCP clients

Choose a Streamable HTTP connection and send Authorization: Bearer <your-agent-key> on each request. Environment syntax and secret storage differ by client. Serpkin currently uses static agent keys rather than an MCP OAuth consent server. A client that only offers OAuth cannot be assumed compatible. Inspect its supported authentication options before creating a connection.

Call serpkin_get_workspace. Show the available sites and my key's access. Ask which site I mean if the choice is ambiguous.

The connection supplies the workspace id. Existing clients may still pass project_id explicitly; a different workspace id is rejected. Discovery is paginated, so follow next_cursor when the chosen site is not on the first page. Tools-only clients do not need MCP resources, slash commands or a local .serpkin.json. A read-only response should never be presented as permission to start work.

#Delegate and follow work

Read serpkin_weekly_summary and serpkin_next_mission for the chosen site. To delegate, fetch serpkin_get_handoff with the mission id. It returns current site context, mission data, implementation and verification requirements, a revision and status-reading tools. It does not contact another agent, reserve a worker or mark a task as started.

Use a channel you have authorized to pass the brief to an implementation agent with its own appropriate key. Do not include keys in the brief. The receiving agent re-fetches it before editing, checks the revision and status, and stops if work is already complete or no longer relevant. It records acceptance with serpkin_update_mission, submits its actual artifacts and requests verification. The planning agent reads mission history to follow progress. A human still reviews and deploys; later search movement remains correlation.

#When connection or work is blocked

A 401 usually means a missing, unresolved or revoked key. An access-denied result means the operation needs a different role, not a new retry loop. An agent-budget error means credits are charged or reserved against this key's ceiling. Inspect queued work and ask the owner before changing it. A crawl-limit or rendering warning needs a change in coverage conditions before another identical scan can help. The owner can inspect the same evidence in the app and revoke an unused connection at any time.

For project-native setup use the CLI reference. For a worked management routine read SEO with AI agents. Connection examples are based on published client interfaces and Serpkin protocol tests; they do not establish every client version's end-to-end behavior.