markaDocs
MCP

MCP servers

Marka's MCP server does everything the Marka app does. One tool registry, two transports, the hosted gateway and the SDK's stdio bridge that proxies it.

Marka's MCP server does everything the Marka app does: search and list, draft and publish, run orders and shipping, manage billing and connected marketplaces, and contact support. It is one tool registry with two transports: the hosted gateway, and the SDK's stdio bridge, which is a proxy of the gateway. Both list the same tools for the same credential.

Connecting an AI coding agent?

The fastest way is to paste one sentence into the agent. It reads Marka's setup instructions, asks you for an API key, and adds the hosted gateway below to its own config. Agent setup has the sentence, and a guide for Claude Code, Codex, Cursor and OpenCode.

The hosted gateway: one URL, no key

Give your client the address. It opens a browser, you sign in and press Allow, and it is connected. Nothing to paste, nothing to store.

claude mcp add --transport http Marka https://joinmarka.com/api/mcp

Then run /mcp in Claude Code and pick Authenticate. What happens behind that:

  1. The client POSTs to the gateway with no credential and gets a 401 carrying WWW-Authenticate: Bearer resource_metadata="https://joinmarka.com/.well-known/oauth-protected-resource".
  2. It follows that to the protected-resource document, and from there to the authorization-server document.
  3. It registers itself (RFC 7591 dynamic client registration) and opens your browser at the authorization endpoint.
  4. You sign in if you are not already, and a consent screen names the client and shows where it will send you back to. Press Allow.
  5. The client exchanges its code for an access token (PKCE S256 is required) and a refresh token, and stores them itself.

Access tokens last an hour. A refresh token stays valid for thirty days from its last use, so a client you keep using stays connected indefinitely and one you stop using falls off after a month. Disconnecting is what actually ends access: under Settings → Connected apps you can see every client you have authorized, and disconnecting one takes effect immediately and revokes every token it holds.

Check the callback address on the consent screen

Any application can register itself under any name, so the name on the consent screen is not proof of anything. The callback origin shown beside it is: a client that says "Claude" but sends you back to somewhere else is not Claude.

API keys still work here

An mk_ key in x-api-key or Authorization: Bearer is accepted on the same endpoint, unchanged. That is the right credential when there is no browser to open — a script, a cron job, a CI step:

claude mcp add --transport http Marka https://joinmarka.com/api/mcp \
  --header "x-api-key: mk_YOUR_KEY_HERE"

The difference is what you are holding. A key is long-lived and sits in a config file; an OAuth token is short-lived, refreshable, and revocable from Settings without invalidating anything else.

Not a browser cookie

This endpoint does not accept a signed-in browser session. Its tools mutate listings, and it stays a credential-bearing machine endpoint rather than becoming a second, cookie-authenticated door into those mutations. A missing or rejected credential answers 401 with the WWW-Authenticate challenge above.

GET on this URL answers 405 with an Allow: POST header — the endpoint is POST-only, and says so rather than letting a 404 stand in for it.

Which transport

HostedStdio bridge
Where it runsMarka's serversyour machine, proxying the hosted gateway
How you reach itPOST https://joinmarka.com/api/mcpstdio subprocess
How you authenticateOAuth in your browser, or an API keyan API key
Toolsthe same registry, listed by search_toolsthe same, forwarded verbatim

Use the hosted server if your client speaks streamable HTTP. Use the bridge if your client can only spawn a stdio subprocess. See Confirmations and handoffs for what a tool does when it needs your confirmation or your browser.

More on the hosted gateway

A request without a usable credential answers 401 with the WWW-Authenticate challenge above and a JSON body of two fields: error, a short string saying what was wrong, and hint, the next step in a sentence an agent can pass on to its user, with links to the API keys page and the agent setup guide.

errorCause
missing api keyNo x-api-key or Authorization header was sent
invalid api keyThe key is unknown, revoked, or expired: create a new one
invalid access tokenThe OAuth token is unknown, revoked, or expired: refresh it or sign in again
cookie sessions are not accepted; an api key is requiredA signed-in browser cookie arrived instead of a key

Its tools are listed on Tools, generated from the server's own registry.

By default the gateway does not list them all as tools. A client sees two, search_tools and execute_typescript: search_tools returns the operations your credential reaches as TypeScript declarations, and execute_typescript runs a short program that calls them as external_<operation>(input), for example return await external_search_listings({ query: "chair" });. Each call runs the operation with the same authentication and checks as calling it directly. A program that fails still comes back from a successful execute_typescript call, with success: false and the error in its result, so read the result rather than the call status. If your client lists the operations as tools instead, it calls them directly.

OAuth scopes and key tiers

A connection or an API key is granted permission tiers. The consent screen says in words what each one allows, and an API key can be created with only the tiers an agent needs.

ScopeTierAllows
marka:readreadReads: search, listings, orders, messages, settings
marka:writewriteEverything read does, plus create and edit: drafts, orders, messages, settings
marka:destructivedestructivePublish, pause, remove, cancel, void and delete actions
marka:billingbillingStart a purchase, cancel or refund your subscription, buy shipping labels
marka:accountaccountProfile, preferences and account deletion
marka:connectionsconnectionsConnect and disconnect Stripe, eBay, Shopify and Easyship
marka:supportsupportOpen support tickets
marka:keyskeysCreate, rotate and revoke API keys

Any tier implies read. A connection granted marka:read alone is not shown the write tools by search_tools, and a call to one answers SCOPE_MISSING with next pointing at request_scopes. A grant that only holds the older marka:write scope keeps reading and writing, but never destructive actions: those need a new consent. A client that asks for no marka: scope at all (every client that predates them, and any that only asks for openid) keeps the full set, and an API key without stored tiers keeps every tool.

What the write tools cost

The hosted draft tools consume your AI copilot run quota — the same monthly allowance the AI assistant on joinmarka.com draws on. On the free plan that is 3 runs per month; Pro and Business are unlimited. Exceeding it fails the tool call rather than silently doing nothing.

They do not go through /api/v1, so they do not require the api_write entitlement. This is the one place the two surfaces genuinely diverge in what a free-plan credential can do: it can draft a listing through the hosted MCP server (up to the copilot quota) but cannot create one through POST /api/v1/listings.

Publishing and destructive actions

publish_listing, pause_listing, remove_listing, cancel_order and the other destructive tools return a confirmToken the first time. Tell the user what will happen, then call again with the token. It works once, for ten minutes, for exactly those arguments.

Connecting

Any other MCP client that speaks streamable HTTP can use the hosted gateway with a config block of this shape — no credential in the file:

{
  "mcpServers": {
    "Marka": {
      "type": "http",
      "url": "https://joinmarka.com/api/mcp"
    }
  }
}

getMcpOAuthServerConfig() from the SDK returns the same block, except that @joinmarka/sdk 0.2.x still names the key marka. Either name works. For the API-key form, use getMcpServerConfig({ apiKey }).http instead.

On this page