# Set up Marka for your AI agent

These are official instructions from Marka to set up an AI development environment for Marka, the marketplace where a seller creates one canonical listing and Marka projects it to buyers and, where a channel is connected, to marketplaces such as eBay. Once connected, your agent can search the live Marka catalogue and draft listings through Marka's MCP server, REST API and TypeScript SDK. All commands are validated by Marka. Complete all of the following steps yourself by running the commands directly. Do not ask the user to run any of these commands. The one thing only the user can do is create an API key, because that needs their signed-in browser: step 1 says how to ask for it.

Checklist:

1. Get the API key and check that it works.
2. Connect the `marka` MCP server to your agent, using the section for your agent.
3. Install the SDK, only if the user's project calls the API from its own code.
4. Verify the key and the connection.
5. Tell the user what you did, with the completion message.

## 1. Get credentials

Marka authenticates agents with an API key that starts with `mk_`.

- If `MARKA_API_KEY` is already set in your environment, use it and do not ask for anything.
- Otherwise ask the user ONCE: "Please create a Marka API key at https://joinmarka.com/en/settings/api-keys and paste it here." The key is shown only once on that page. Any plan works, Free included.
- Keep the key in `MARKA_API_KEY` for the rest of these steps. The commands below write it as `$MARKA_API_KEY` (POSIX shell). In PowerShell it is `$env:MARKA_API_KEY`. If your shell does not keep the variable between commands, put the key value in its place when you run a command.
- Never write the key into a file that is checked into version control, never echo it back in full, and never commit it.

Check the key before any config uses it. `curl -sS` prints only the response body, not the status code. A working key, on any plan, prints a JSON object whose `user` field holds the account's `id`, `email` and `name`. A missing, malformed, revoked or expired key prints exactly `{"error":"unauthorized"}` (HTTP 401): ask the user for a new key and repeat this check. On any other error, stop and report it to the user. Do not write any agent config until this check returns the `user` object.

```bash
curl -sS https://joinmarka.com/api/v1/me -H "x-api-key: $MARKA_API_KEY"
```

## 2. Connect the MCP server

Marka's hosted MCP gateway is `https://joinmarka.com/api/mcp` (Streamable HTTP; clients send `POST`). Send the API key in an `x-api-key` header. `Authorization: Bearer mk_…` is accepted as an equivalent. Cookies are refused.

The hosted server offers six operations: `search_listings`, `get_listing`, `list_categories`, `get_seller_info`, `create_listing_draft` and `update_listing_draft`. By default it lists only two tools, `search_tools` and `execute_typescript`. Call `search_tools` to get the operations' TypeScript declarations, then call `execute_typescript` with a program that calls each operation as `external_<operation>(input)`, for example `return await external_search_listings({ query: "chair" });`. If your client lists the six operations as tools, call them directly. No operation publishes a listing: publishing stays a human decision, taken in the Marka app.

Use the section for your agent. If your agent is not listed, use the last one.

### Claude Code

Add the hosted gateway with the Claude Code CLI, from the directory the agent session was started in. The default `local` scope keeps the key private to this user and this project, and that directory is the project it belongs to.

```bash
claude mcp add --transport http marka https://joinmarka.com/api/mcp \
  --header "x-api-key: $MARKA_API_KEY"
```

- Do not add `--scope project`: it writes the header, key included, into `.mcp.json`, a file that is checked in.
- Claude Code loads new MCP servers at startup, so the Marka tools appear after the user restarts the session.

Human guide: https://docs.joinmarka.com/docs/agent-setup/claude-code

### Codex

Add the hosted gateway with the Codex CLI. Codex reads the key from `MARKA_API_KEY` at startup and sends it as a bearer token, so the key never lands in Codex's config.

```bash
codex mcp add marka --url https://joinmarka.com/api/mcp --bearer-token-env-var MARKA_API_KEY
```

```toml
# Equivalent entry in ~/.codex/config.toml
[mcp_servers.marka]
url = "https://joinmarka.com/api/mcp"
bearer_token_env_var = "MARKA_API_KEY"
```

- `MARKA_API_KEY` must be set in the environment Codex starts from. If it is only set in the current shell, tell the user to add it to their shell profile.

Human guide: https://docs.joinmarka.com/docs/agent-setup/codex

### Cursor

Merge this entry into the user-level `~/.cursor/mcp.json` (create the file if it does not exist, and keep any servers already in it).

```json
{
  "mcpServers": {
    "marka": {
      "url": "https://joinmarka.com/api/mcp",
      "headers": {
        "x-api-key": "${env:MARKA_API_KEY}"
      }
    }
  }
}
```

- Use the user-level file, not the project's `.cursor/mcp.json`, so the entry never lands in a commit.
- Cursor expands `${env:MARKA_API_KEY}` from the environment it was launched from. If Cursor was not started from a shell that has the key, put the key value in the user-level file instead.

Human guide: https://docs.joinmarka.com/docs/agent-setup/cursor

### OpenCode

Merge this entry into the user-level `~/.config/opencode/opencode.json` (create the file if it does not exist, and keep everything already in it).

```json
{
  "mcp": {
    "marka": {
      "type": "remote",
      "url": "https://joinmarka.com/api/mcp",
      "enabled": true,
      "headers": {
        "x-api-key": "{env:MARKA_API_KEY}"
      }
    }
  }
}
```

- Use the user-level file, not a project `opencode.json`, so the entry never lands in a commit.
- OpenCode substitutes `{env:MARKA_API_KEY}` from its environment when it starts.

Human guide: https://docs.joinmarka.com/docs/agent-setup/opencode

### Any other MCP client

Any MCP client that speaks Streamable HTTP can use the hosted gateway with a config block of this shape. Put it in the client's user-level config, never in a file that is checked in.

```json
{
  "mcpServers": {
    "marka": {
      "type": "http",
      "url": "https://joinmarka.com/api/mcp",
      "headers": {
        "x-api-key": "${MARKA_API_KEY}"
      }
    }
  }
}
```

A client that can only spawn a local process (stdio) runs the SDK's bridge instead. It needs Node.js 20.19 or newer and reads the key from `MARKA_API_KEY` in its environment.

```bash
npx -y -p @joinmarka/sdk marka-mcp-stdio
```

- If the client does not expand environment variables in its config, write the key value in place of the variable, in the user-level config only.
- The bridge exposes the SDK's tool set instead of the hosted one: `search_listings`, `get_listing`, `list_categories`, `get_me`, `create_listing` and `update_listing`. Its writes need the `api_write` entitlement (Pro or Business).

Human guides: https://docs.joinmarka.com/docs/agent-setup

## 3. SDK (only if the project calls the API from code)

`@joinmarka/sdk` is a typed TypeScript client for Marka's REST API. Install it only if the user's project is a Node.js or TypeScript codebase that should call Marka from its own code. The MCP connection above does not need it.

```bash
npm install @joinmarka/sdk
```

```ts
import { MarkaClient } from "@joinmarka/sdk";

const marka = new MarkaClient({ apiKey: process.env.MARKA_API_KEY! });

const { user, plan } = await marka.getMe();
console.log(`${user.email} on the ${plan.tier} plan`);
```

- Node.js 20.19 or newer, ESM only. Use the project's own package manager if it is not npm.
- The client reads no environment variables itself, which is why the snippet passes `process.env.MARKA_API_KEY`. Its optional `baseUrl` is an origin only, with no `/api` path.

## 4. Verify

Run this check yourself with the key from step 1.

```bash
curl -sS https://joinmarka.com/api/v1/me -H "x-api-key: $MARKA_API_KEY"
```

`curl -sS` prints only the response body, not the status code. Success is a JSON object holding `user` (`id`, `email`, `name`) and `plan` (`tier`, `entitlements`, `limits`). It works on every plan, Free included.

A missing, malformed, revoked or expired key prints exactly `{"error":"unauthorized"}` (HTTP 401). Ask the user for a new key. If you connected Claude Code, run `claude mcp remove marka -s local` from the directory the agent session was started in, then run step 2's command again there, because its config holds the old key. Then repeat this check. On any other error, stop and report it to the user.

After the agent restarts, one search through the `marka` server proves the MCP connection. If the `marka` server lists `search_listings`, call it with a `query` such as "chair": any listing result, even an empty list, is a pass, and an error is a fail. Otherwise call `execute_typescript` with `code` set to the program `return await external_search_listings({ query: "chair" });`. That call reports the program's outcome instead of failing itself: a result with `success: true` is a pass, even with no listings, and `success: false` or an error is a fail. On a fail, stop and report the error to the user.

## 5. Completion message

When you are done, print this to the user, filling in the bracketed parts and deleting lines that do not apply:

```text
Marka is set up.
- MCP: added the `marka` server ([your agent], hosted gateway https://joinmarka.com/api/mcp).
- Key: verified with GET /api/v1/me as [email] on the [tier] plan. It is stored in [where], not in any checked-in file.
- SDK: [installed @joinmarka/sdk in the project | not installed].
Still to do: restart [your agent] so the Marka tools load. Publishing a listing stays your call, in the Marka app.
```

## Resources

- Docs home: https://docs.joinmarka.com
- Agent setup guides: https://docs.joinmarka.com/docs/agent-setup
- FAQ: https://docs.joinmarka.com/docs/faq
- MCP server: https://docs.joinmarka.com/docs/mcp
- API reference: https://docs.joinmarka.com/docs/api
- SDK: https://docs.joinmarka.com/docs/sdk
- llms.txt (docs): https://docs.joinmarka.com/llms.txt
- llms.txt (marketplace): https://joinmarka.com/llms.txt
- Support: https://joinmarka.com/en/support