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/mcpThen run /mcp in Claude Code and pick Authenticate. What happens behind that:
- The client POSTs to the gateway with no credential and gets a
401carryingWWW-Authenticate: Bearer resource_metadata="https://joinmarka.com/.well-known/oauth-protected-resource". - It follows that to the protected-resource document, and from there to the authorization-server document.
- It registers itself (RFC 7591 dynamic client registration) and opens your browser at the authorization endpoint.
- 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.
- The client exchanges its code for an access token (PKCE
S256is 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
| Hosted | Stdio bridge | |
|---|---|---|
| Where it runs | Marka's servers | your machine, proxying the hosted gateway |
| How you reach it | POST https://joinmarka.com/api/mcp | stdio subprocess |
| How you authenticate | OAuth in your browser, or an API key | an API key |
| Tools | the same registry, listed by search_tools | the 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.
error | Cause |
|---|---|
missing api key | No x-api-key or Authorization header was sent |
invalid api key | The key is unknown, revoked, or expired: create a new one |
invalid access token | The OAuth token is unknown, revoked, or expired: refresh it or sign in again |
cookie sessions are not accepted; an api key is required | A 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.
| Scope | Tier | Allows |
|---|---|---|
marka:read | read | Reads: search, listings, orders, messages, settings |
marka:write | write | Everything read does, plus create and edit: drafts, orders, messages, settings |
marka:destructive | destructive | Publish, pause, remove, cancel, void and delete actions |
marka:billing | billing | Start a purchase, cancel or refund your subscription, buy shipping labels |
marka:account | account | Profile, preferences and account deletion |
marka:connections | connections | Connect and disconnect Stripe, eBay, Shopify and Easyship |
marka:support | support | Open support tickets |
marka:keys | keys | Create, 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
Claude Code
claude mcp add, then /mcp to authenticate.
Claude Desktop
A custom connector, or the stdio bridge.
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.
SDK cookbook
Six end-to-end recipes with runnable code — set up the client, create and publish a listing, search the market, reconcile inventory, process orders across both rails, and wire the MCP bridge into an AI client.
Tools
Every operation the hosted MCP gateway serves, its permission tier, and the two tools a client reaches them through by default. Generated from the server's own registry.