Connect in five minutes

By the end of this page your coding agent will know which Semicola account it is connected to and will have read its first objects. You need a Semicola account and an MCP client that supports remote servers over Streamable HTTP. Creating an account or finishing seller onboarding can take longer than the connection itself.

1. Add the connection

Codex
Claude Code
Other MCP clients

codex mcp add semicola --url https://api.semicola.com/mcp/v3
codex mcp login semicola

The login command opens a browser. Sign in to Semicola, pick the account to use, and approve the connection. Then start a Codex session in your project.

claude mcp add --transport http semicola https://api.semicola.com/mcp/v3
claude

Inside Claude Code, run /mcp, choose semicola, and complete sign-in in the browser.

Add a remote server that uses Streamable HTTP with this URL:

https://api.semicola.com/mcp/v3

Choose OAuth as the authentication method. The client discovers everything else from the server’s first 401 response. See MCP client setup for host-specific notes.

If your client already has a Semicola connection that points at this URL, reuse it. Your agent should never ask you to paste a password or key into the chat.

OAuth connects the coding session as you. It is not an identity for software you deploy later. For a headless service, create an API key and keep it in a secret manager; see Authentication.

Running the Semicola stack locally? Use http://localhost:4000/mcp/v3 instead. The local server plays the sign-in role itself, with the same discovery documents.

2. Prove account access

Ask your agent:

Use the semicola connection to call get_status. Tell me the active account, whether it is a buyer
or a seller, any readiness blockers, and which other accounts I can reach. Do not create or change
anything.

If the client reports that the connection still needs authentication, finish OAuth in its MCP controls and try again. Adding a server is not the same as signing in. A successful get_status proves the connection reaches your account. It does not prove that every advertiser, seller or write is allowed. If the wrong account is active, call switch_account with a customerId from the status result’s reachableAccounts, then call get_status again. The table at the end of this page covers what to check when a tool you expected is missing.

3. Make a first read

Ask the agent to look at tools/list, then call search with the input that suits your account:

Buyer account
Seller account

{ "kind": "seller", "limit": 10 }

This lists sellers and their connection and readiness status for your account. It does not send anyone a brief. An empty list is a valid answer, not a broken connection.

{ "kind": "inventory_source", "limit": 10 }

This lists the inventory sources connected to your storefront. A new storefront may have none yet.

You now have a verified connection and one account-scoped read. The schemas in tools/list are the contract for this session; they can differ by account, role and feature availability.

4. Build a small prototype

A good first project is a read-only seller browser for a buyer account:

Build a small seller-discovery prototype in this repository using the semicola MCP connection.
Check the account with get_status and read the current tool schemas. List sellers and show their
readiness and connection status. Keep credentials out of the repository. Add a fixture test for a
populated result and one for an empty result. Do not request proposals or create a campaign yet.
Explain how to run it and what the tests prove.

The fixture tests prove your code handles the shapes; the live get_status and search calls prove account access. Neither proves a campaign can launch. When you are ready to write, read the Campaign object guide and the v3 Tool Catalog.

If the first call fails

What you see	What to do
Authentication required	Finish OAuth in the client’s MCP controls, then retry.
Wrong account, or buyer or seller tools missing	Read `reachableAccounts` from `get_status`, switch to the right account, and refresh the tool list.
Permission denied	The credential’s account or role lacks access. Reinstalling the connection does not change permissions.
A readiness blocker	Follow the next action `get_status` returns. A working connection does not finish commercial setup.
The client cannot show a widget	Use the structured result or text summary, or switch to a host that supports MCP Apps.

v3

Concepts

Agents

Skills

Buyer API reference

Storefront API reference

v3 API reference

Connect in five minutes

1. Add the connection

2. Prove account access

3. Make a first read

4. Build a small prototype

If the first call fails

​1. Add the connection

​2. Prove account access

​3. Make a first read

​4. Build a small prototype

​If the first call fails

1. Add the connection

2. Prove account access

3. Make a first read

4. Build a small prototype

If the first call fails