How to Add an MCP Server to Claude Code, Codex, Cursor and Windsurf (With a Video Generation Example)

Remote MCP servers are the fastest way to give a coding agent a new capability without writing an integration. This guide shows the exact commands and config files for Claude Code, Codex, Cursor, Windsurf and VS Code, using one concrete server as the worked example: Shortzly's video server at https://shortzly.com/mcp, which turns a script your agent writes into a rendered, captioned reel. Swap the URL and the steps apply to any remote MCP server.

Before you start: OAuth or a token?

Remote MCP servers over HTTP authenticate in one of two ways, and every client below supports both.

• OAuth 2.1. The client registers itself with the server, opens your browser, you approve, and the client stores a refreshable grant. Nothing to copy. Best on your own machine.
• Bearer token. You mint a token in the server's dashboard and pass it as an Authorization header. Best for CI, containers and shared environments where a browser flow is awkward.

For Shortzly, tokens are created under Settings, API tokens. They look like <id>|shz_<secret>, carry only the mcp:use ability, are shown once, and can be revoked individually. Paste the whole string, including the numeric id and the pipe, as the bearer token.

Claude Code

Claude Code manages servers with the claude mcp subcommand. For a remote HTTP server:

claude mcp add --transport http shortzly https://shortzly.com/mcp

Start Claude Code, type /mcp, pick Shortzly and complete the sign-in in your browser. From then on the server's tools are available in every session in that project. To use a token instead of OAuth:

claude mcp add --transport http shortzly https://shortzly.com/mcp \
  --header "Authorization: Bearer <id>|shz_..."

Useful flags: --scope user makes the server available in every project rather than the current one, and claude mcp list shows what is configured. Remove with claude mcp remove shortzly.

To share the server with everyone who clones a repository, use --scope project. Claude Code then writes the entry to a .mcp.json file in the project root, which you can commit. Teammates are asked to approve the server the first time they open the project, and each of them completes their own OAuth sign-in, so no credential ever lands in version control. This is the setup we use for the launch-video pipeline described at the end of this guide.

Try it

Use Shortzly to make a 30-second 9:16 reel explaining what an MCP server is.
Six segments, stock footage, Nova voice, CapCut captions. Render a preview
and give me the download link.

Claude Code will call get_capabilities, write the segments, call create_reel, poll get_job and hand you the URL from get_clip. Ask it to upgrade to HD and publish once you have watched the preview.

Codex

OpenAI's Codex CLI has an equivalent codex mcp subcommand:

codex mcp add shortzly --url https://shortzly.com/mcp
codex mcp login shortzly

The second command runs the OAuth flow and stores the grant. For a token, add the server to ~/.codex/config.toml and point it at an environment variable instead of pasting the secret into the file:

[mcp_servers.shortzly]
url = "https://shortzly.com/mcp"
bearer_token_env_var = "SHORTZLY_MCP_TOKEN"

export SHORTZLY_MCP_TOKEN="<id>|shz_..."

codex mcp list confirms the server is registered.

Cursor

Cursor reads MCP servers from .cursor/mcp.json in a project, or ~/.cursor/mcp.json for all projects. Remote servers use a url key and optional headers:

{
  "mcpServers": {
    "shortzly": {
      "url": "https://shortzly.com/mcp",
      "headers": {
        "Authorization": "Bearer <id>|shz_..."
      }
    }
  }
}

Open Cursor settings, MCP, and confirm the server shows a green status and a tool count of 14. Cursor also supports OAuth for remote servers: omit headers and click the login prompt that appears next to the server.

Windsurf

Windsurf uses the same JSON shape in ~/.codeium/windsurf/mcp_config.json, with serverUrl as the key name for remote servers:

{
  "mcpServers": {
    "shortzly": {
      "serverUrl": "https://shortzly.com/mcp",
      "headers": {
        "Authorization": "Bearer <id>|shz_..."
      }
    }
  }
}

Reload Windsurf and check the MCP panel in Cascade. If the tools do not appear, the most common cause is a stale token; mint a new one and replace the header.

VS Code

VS Code's built-in agent mode reads .vscode/mcp.json. The key is servers rather than mcpServers, and remote servers declare "type": "http". VS Code can prompt for the secret so it never lands in the file:

{
  "inputs": [
    { "id": "shortzly-token", "type": "promptString",
      "description": "Shortzly MCP token", "password": true }
  ],
  "servers": {
    "shortzly": {
      "type": "http",
      "url": "https://shortzly.com/mcp",
      "headers": { "Authorization": "Bearer ${input:shortzly-token}" }
    }
  }
}

Run MCP: List Servers from the command palette to start it and see the tools.

Checking that it works

Whatever the client, the first thing to ask is a read-only tool call. For Shortzly: "Call get_account and tell me how many reels I have left this month." A correct answer proves the transport, the authentication and the tool discovery all work, without spending anything. Then ask for a preview render, which costs half a credit.

Common problems

• 401 Unauthorized. The token was pasted without the numeric id and the pipe, or it was revoked. Mint a new one and paste the whole string.
• Tools list is empty. The client connected but did not complete OAuth. Run the login step again (/mcp in Claude Code, codex mcp login in Codex, the login prompt in Cursor).
• 429 Too Many Requests. Shortzly allows 120 requests per minute per user. Agents that poll get_job in a tight loop hit this; the response includes a retry_after_seconds hint and well-behaved clients honor it.
• The agent rendered twice. Pass an idempotency_key in create_reel. A retried call with the same key returns the original job.
• Media URL rejected. Shortzly fetches media through an SSRF guard: https only, no private or loopback addresses, redirects re-checked. Localhost URLs and http URLs are refused by design. Upload the file through create_upload instead.

Why a video server is a good first MCP server

Most MCP servers people add first are read-heavy: documentation, issue trackers, databases. A video server is a good test of the write side. It exercises uploads, long-running jobs, polling, idempotency and a publish step with real-world consequences, and the result is something you can watch. If your agent can take a paragraph and turn it into a posted reel, it can handle most tool-calling work you will throw at it.

The tool list, cost model and security notes for Shortzly's server are on the MCP server page. The launch post, Introducing the Shortzly MCP Server, has a full create_reel example. If you are on the chat side rather than the terminal, see how to make videos from ChatGPT.

Frequently asked questions

What is the difference between a local and a remote MCP server?

A local server is a process your client starts on your machine and talks to over standard input and output. A remote server is an HTTPS endpoint you connect to, authenticated with OAuth or a token. Remote servers need nothing installed and work from any machine or cloud agent.

Can I add the same server to more than one client?

Yes. Each client keeps its own OAuth grant or token. In Shortzly, every connected app and token is listed under Settings, API tokens and MCP, and each can be revoked on its own.

Does the server cost anything to add?

No. Shortzly's MCP server is included on every plan. Rendering a reel uses your normal monthly quota: half a credit for a preview, one credit for HD.