OpenCode Integration with ShortURL MCP

📘 Overview：OpenCode MCP Overview →

You have just generated a set of video, image, or document links using OpenCode and need to share them with colleagues or post them in a group. The original URLs are long and unattractive, and copying and pasting can easily lead to line breaks and misalignment. After connecting to the ShortURL MCP Server, OpenCode can compress all links into surl.id short links at once, returning the results directly for easy copying and pasting.

ShortURL MCP is suitable for organizing and sharing links in OpenCode, batch replacing document links with short links, or unifying external link formats in published materials. It is fast and cost-effective, making it one of the best services for "experiencing MCP first."

Obtain API Token

Before using the ShortURL MCP Server, you need to prepare an Ace Data Cloud API Token. OpenCode and Claude Code share the same set of tokens, and the acquisition process is the same:

  1. Open the Ace Data Cloud Console - Application List to obtain your API Token for backup.
  2. If you are not logged in or registered, you will be automatically redirected to the login page; after logging in or registering, you will be returned to the current page.
  3. The first application will grant a free quota, allowing you to experience the ShortURL MCP service for free.

Obtain Ace Data Cloud API Key

One token can be used for all MCP Servers provided by Ace Data Cloud, and there is no need to apply separately for ShortURL. The documentation and screenshots suggest displaying only a desensitized format, such as YOUR_ACEDATACLOUD_API_KEY, and not posting the complete token in public repositories, issues, screenshots, or chat records.

Want to use Claude Desktop / Claude.ai web version for direct OAuth one-click authorization? Please see the Claude.ai / Desktop tutorial for ShortURL MCP.

Configure OpenCode

OpenCode describes all MCP Servers in a single opencode.json file, which can be placed in two locations; choose one according to the "scope of application" below. The field structure in both locations is identical, with the only difference being priority.

It is strongly recommended to first write the token to an environment variable:

export ACEDATACLOUD_API_KEY="replace with your real token"

Then reference it in opencode.json using the {env:ACEDATACLOUD_API_KEY} placeholder to avoid writing the real token into the file.

Global: Shared by All Projects

File location: ~/.config/opencode/opencode.json, suitable for "my own machine, configured once, usable by all projects."

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "shorturl": {
      "type": "remote",
      "url": "https://shorturl.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}" }
    }
  }
}

⚠️ "oauth": false cannot be omitted. AceData's MCP Server uses Bearer Token authentication and does not go through the OAuth process; OpenCode will automatically redirect 401 as an OAuth challenge, resulting in opencode mcp list showing SSE error: Non-200 status code (401). Explicitly declaring "oauth": false allows OpenCode to call directly with Authorization: Bearer ..., and opencode mcp debug shorturl will also echo OAuth explicitly disabled, indicating it is effective.

Project-Level: Effective Only for Current Project

File location: opencode.json in the root directory of the current project, which will override the global configuration. Suitable for team sharing, single repository customization, or temporarily enabling a specific MCP in a project.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "shorturl": {
      "type": "remote",
      "url": "https://shorturl.mcp.acedata.cloud/mcp",
      "enabled": true,
      "oauth": false,
      "headers": { "Authorization": "Bearer {env:ACEDATACLOUD_API_KEY}" }
    }
  }
}

If the project-level opencode.json will be committed to Git, please ensure to use the {env:ACEDATACLOUD_API_KEY} placeholder instead of the real token to avoid leakage.

💡 If the .env in Shell is not explicitly exported, you need to use set -a && source .env && set +a to pass the variables to the OpenCode process; otherwise, opencode debug config will show "Authorization": "Bearer " (placeholder not resolved).

Verify Connection

After configuration, run:

opencode mcp list
opencode mcp debug shorturl

Seeing shorturl connected indicates a successful handshake. If it fails, check whether ACEDATACLOUD_API_KEY has been exported, whether oauth is set to false, and whether Authorization includes the Bearer prefix. The model and tool schema will continue to change, so please select a model that supports native tool calls from the current directory.

Typical Scenarios

After configuration, you can directly call it in the OpenCode session using natural language without switching to /mcp:

Single Shortening

Shorten this link: https://platform.acedata.cloud

Batch Shortening

Shorten the following 5 release notes links and send them out:
...

Sharing with Non-Technical Colleagues

Shorten these document links; I want to send them to the group.

Tool List

The table below lists the main tools; you can obtain the current complete list by using curl -X POST https://shorturl.mcp.acedata.cloud/mcp -H 'Authorization: Bearer <token>' -H 'Accept: application/json' -H 'Content-Type: application/json' --data '{"jsonrpc":"2.0","id":1,"method":"tools/list"}':

Tool Description
shorturl_create Generate short link
shorturl_batch_create Batch generate short links
shorturl_get_api_info Get API information
shorturl_get_usage_guide Get usage guide