How to connect an AI assistant to DockAccess with MCP

DockAccess runs an MCP (Model Context Protocol) server. It lets an AI assistant, such as Claude Code, OpenAI Codex CLI or Gemini CLI, work with your DockAccess account on your behalf. The assistant can check your plan limits, list your sites and their services, start an automatic audit, and show audit results, subscriptions and invoices.

The assistant sees only your company and only the tools you select when you create the key.

At a glance

• Server address: https://dockaccess.org/mcp
• Transport: Streamable HTTP (JSON-RPC 2.0, plain JSON responses, no SSE, no session)
• Authentication: the header Authorization: Bearer <MCP key>. The key starts with dockaccess_mcp_.
• Where to create a key: My account → MCP access (https://dockaccess.org/my-account/mcp/)
• Who can create a key: a person with the Owner, Administrator or Developer role in the company
• Supported MCP protocol versions: 2025-11-25, 2025-06-18, 2025-03-26
• Scope: one company (the one the key was created in), the selected tools, the same plan limits as in the panel

Step 1. Create an MCP key

1. Sign in at dockaccess.org and choose the company the assistant should work with. The key belongs to the company that is active when you create it.
2. Open My account → MCP access.
3. Enter a key name, for example “Claude Code on my laptop”. The name tells keys apart on the list.
4. Set how many days the key is valid, from 1 to 365. After that the key stops working.
5. Select the allowed tools. Tools marked “write” change data, for example add a site or start an audit. Select only what the assistant really needs.
6. Click Generate key and copy the secret right away. The secret is shown only once. DockAccess stores only its hash, so it cannot be recovered. You can only create a new key.

When a key is created, its owner receives a notification e-mail. The e-mail never contains the secret. If you did not create the key, revoke it immediately.

Step 2. Add the server to your MCP client

In every example, replace YOUR_MCP_KEY with the secret you copied.

Claude Code

claude mcp add --transport http dockaccess https://dockaccess.org/mcp --header "Authorization: Bearer YOUR_MCP_KEY"
Copy text

OpenAI Codex CLI

Codex reads the secret from an environment variable, so it never ends up in the configuration file:

export DOCKACCESS_MCP_KEY=YOUR_MCP_KEY
codex mcp add dockaccess --url https://dockaccess.org/mcp --bearer-token-env-var DOCKACCESS_MCP_KEY
Copy text

Gemini CLI

gemini mcp add --transport http --header "Authorization: Bearer YOUR_MCP_KEY" dockaccess https://dockaccess.org/mcp
Copy text

Other clients (JSON configuration file)

Clients that support remote HTTP servers with custom headers are usually configured like this:

{
  "mcpServers": {
    "dockaccess": {
      "type": "http",
      "url": "https://dockaccess.org/mcp",
      "headers": { "Authorization": "Bearer YOUR_MCP_KEY" }
    }
  }
}
Copy text

The details depend on the client, such as the file name and whether the field is called type, transport or url. Look for “remote MCP server” or “Streamable HTTP” in its documentation.

What cannot be connected

The DockAccess server authenticates only with a key in the Authorization header. There is no OAuth. Clients that support only OAuth for remote servers and do not let you add your own header cannot connect directly. Some connectors in web-based AI chat apps work this way. In that case use a command-line client (Claude Code, Codex CLI, Gemini CLI) or a code editor that lets you set the header.

Step 3. Check the connection

Ask the assistant, for example: “Show my DockAccess plan limits”. The assistant should call the limits_get tool and return, among other things, this month's widget views and the audits used today.

If the assistant does not see any DockAccess tools, go to the “Troubleshooting” section.

Available tools

The assistant sees the tools that are both selected in the key and allowed by your permissions in the company. If one of your permissions is removed, the tool disappears from the key at once, without creating a new key.

Account and limits

• account_get (read): your company in DockAccess: name, billing details, currency and number of active subscriptions.
• limits_get (read): plan limits and current usage: widget views this month, the number of sites using each service, automatic audits used today.

Sites (widget tokens)

• sites_list (read): your company's sites with their domains and enabled services. Optional arguments: search (text), page (results page, from 1).
• sites_get (read): one site: domains, services (widget, ALT generator, monitoring) and their state. Required argument: site, the site token from the token field of sites_list.
• sites_create (write): adds a site. Required argument: domains, a list of domains, e.g. ["example.com"]. Optional: widget, alt, monitoring (true/false). A service over the plan limit is created switched off, and the result says which one and why.
• sites_set_service (write): switches a service of a site on or off. Required arguments: site, service (widget, alt or monitoring), enabled (true/false). Switching on over the plan limit is refused, with the reason.

Automatic audits

• audits_list (read): audited addresses of a site with the latest desktop and mobile scores. Required argument: site. Optional: search, page.
• audits_history (read): past audits of one address. Required arguments: site and address (the address_uuid from audits_list). Optional: page.
• audits_scan (write): starts an automatic audit of a page. Required arguments: site and url: a full URL on the site's domain, a domain, or a path such as /contact. Optional: lang (en or pl, the report language, en by default). The audit counts against the daily audit limit. The tool returns the audit id; results arrive within minutes and can be checked with audits_list.

Subscriptions and invoices

• subscriptions_list (read): your company's subscriptions: plan, status, period, price, next payment.
• subscriptions_get (read): details of one subscription. Required argument: subscription (the subscription id, a UUID).
• invoices_list (read): your company's issued invoices. Optional argument: page.

Who sees which tools

The tools depend on your role in the company:

• Owner and Administrator see all customer tools and can create keys.
• Developer can create keys and sees the account, site and audit tools, but not subscriptions or invoices.
• Tester, Accountant and other roles cannot create MCP keys.

Write tools and safe retries

Every write tool (sites_create, sites_set_service, audits_scan) needs an operation_id argument: a unique UUID generated by the client. It makes the operation run exactly once:

• a retry with the same operation_id and the same arguments (e.g. after a dropped connection) does not repeat the operation; it returns its first result;
• the same operation_id with different arguments is refused;
• a new operation needs a new operation_id.

AI assistants generate this id themselves, because the tool schema describes it.

Limits

• Plan limits are the same as in the panel, because the tools use the same mechanisms. MCP gives access to nothing you cannot do in the panel.
• The daily automatic audit limit includes audits started through MCP. When it is used up, the tool returns an explanation instead of a technical error.
• MCP server request limits:
  • 60 per minute per key;
  • 180 per minute per person (all of their keys together);
  • 120 per minute per IP address.

Security

• One company per key. A key works only in the company it was created in. Tool arguments cannot change this, and another company's data is “not found” for the key.
• Selected tools only. A key allows only the tools selected when it was created, further limited by your current permissions.
• The secret is stored as a hash. Nobody at DockAccess can see your secret, and the e-mail about a new key never contains it.
• No access from browsers. The server refuses requests sent from web pages on other domains, so a third-party page cannot call tools with your key.
• Strict argument validation. Unknown fields, wrong types and values outside the allowed list are refused.
• Activity log. Every call is recorded in your company's activity log as an MCP event with the tool name. Arguments and results are not stored.
• Revoking. Revoke a key in My account → MCP access with the “Revoke” button. The assistant loses access immediately.

A key also stops working when:

• it expires;
• the key owner's account is deactivated or has an unverified e-mail address;
• the key owner is no longer a member of the company;
• the company is no longer active.

Treat an MCP key like a password: do not paste it into a repository, a chat or a support ticket. If it leaks, revoke it and create a new one.

Example prompts

• “Which sites do I have in DockAccess and which services are enabled on them?”
• “How many automatic audits do I have left today?”
• “Run an audit of the example.com home page and the /contact page.”
• “Compare my home page accessibility score with the previous audit.”
• “Add the site shop.example.com with the widget and monitoring.”
• “When is my next subscription payment and which plan is it?”

The assistant acts only on your explicit request. Most clients ask for confirmation before running a write tool.

How it works (for developers)

The server accepts POST https://dockaccess.org/mcp requests with a JSON-RPC 2.0 body. The client sends the protocol version in initialize or in the MCP-Protocol-Version header. Notifications (notifications/* methods without an id) are answered with 202.

Initialization:

curl -s https://dockaccess.org/mcp \
  -H "Authorization: Bearer YOUR_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'
Copy text

The tools available to the key:

curl -s https://dockaccess.org/mcp \
  -H "Authorization: Bearer YOUR_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":2,"method":"tools/list"}'
Copy text

Calling a write tool (operation_id is a new UUID):

curl -s https://dockaccess.org/mcp \
  -H "Authorization: Bearer YOUR_MCP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"audits_scan","arguments":{"site":"SITE_TOKEN","url":"/contact","lang":"en","operation_id":"6f1c2c1e-8a3b-4a52-9a0e-2f4b1d7c9e10"}}}'
Copy text

A successful call returns the result twice:

• as JSON text in result.content[0].text;
• as an object in result.structuredContent.

When a tool refuses to run, for example when a limit is used up or a service is not subscribed, the response has result.isError: true and a text in the form code: sentence, e.g. limit_exceeded: …. Any other error returns one generic sentence, with no technical details.

Troubleshooting

• The assistant does not see DockAccess tools.
  • Check that the client sends the Authorization: Bearer … header and uses the HTTP transport (Streamable HTTP), not stdio.
  • Check that the key has not expired or been revoked (My account → MCP access).
• Only some tools are visible.
  • A key shows only the tools selected when it was created, within your permissions in the company.
  • Tools cannot be added to an existing key: create a new one with a different set.
• A 401 response. The key is invalid, expired, revoked, or no longer meets the conditions in “Security”.
• A 429 response. The request limit was exceeded. Wait a minute.
• limit_exceeded for an audit or a service. A plan limit is used up. Check limits_get or the pricing.
• You cannot create a key.
  • Keys are created by the Owner, Administrator and Developer roles.
  • A key cannot be created while a DockAccess employee is viewing your account.
• The assistant works on the wrong company. A key belongs to the company that was active when it was created. Switch the company in the panel and create a separate key for it.

Frequently asked questions

Does MCP cost extra?

No, there is no separate fee. Your plan limits apply, just as in the panel.

Can the assistant change payments, delete a site or add someone to the team?

No. Only three tools write data: adding a site, switching a site's service on or off, and starting an audit. Payments, deleting data and team management are available only in the panel.

Can DockAccess see my conversations with the assistant?

No. DockAccess receives only the tool calls. The company activity log stores the tool name and time, without arguments or results.

How many keys can I have?

You can have a separate key for each tool and device, for example “Claude Code – laptop” and “Codex – CI server”. Each one can be revoked independently.