How to Use ZCode with the Twitter (X) API: MCP Server and Skills Setup

A harness, not a model. ZCode wraps a model (GLM by default, but its provider config also accepts OpenAI Chat Completions, OpenAI Responses and Anthropic Messages APIs) in an agent loop with tools, permissions, sessions, MCP, skills, hooks and plugins. Z.ai's ZCode page tells GLM Coding Plan subscribers to set the OpenAI base URL to https://api.z.ai/api/coding/paas/v4 and the Anthropic base URL to https://api.z.ai/api/anthropic, and Z.ai's plan overview lists ZCode with "1.5x Usage".

Three front ends, one agent. The desktop app (macOS, Windows, and Linux in beta per the download page), a browser workbench, and a terminal UI. The repository README says the single zcode command starts the TUI with no arguments, starts Web mode with --web, and passes every other argument to the agent CLI, for example zcode --prompt "..." --cwd /path --mode plan --json for a non-interactive run.

Open source since September 2026. The repository was created on September 20, 2026. A day later, the official ZCode account on X posted that it had fixed security issues reported by the community, open-sourced the client "under community scrutiny", removed the Repo Wiki feature and disabled the workflow that generated and uploaded local repository snapshots in the v3.14.0 client. The README's update log lists v3.16.2 on October 19, 2026; the download page showed v3.16.3 when we checked.

Why that history matters here. An X integration means an API key in a config file and untrusted tweet text flowing into the agent's context. ZCode's docs are explicit about where keys live and which configs load automatically, and the next sections follow them closely.

In the desktop app. Open Settings, then MCP Servers, then New MCP Server. Choose the scope (User, available in all workspaces, is the right one for an API key), give it a name such as twitterapi, switch the type from stdio to HTTP, enter https://mcp.twitterapi.io/mcp, expand Headers and add Authorization with the value Bearer followed by your twitterapi.io API key. ZCode's docs also offer a Full configuration mode that accepts pasted JSON in either {"server-name": {...}} or {"mcpServers": {...}} shape.

By hand. The same entry in the user config file is below. The CLI usage guide says to make sure features.mcp is enabled and that every server must declare its transport type. The http type accepts url, optional headers, oauth, timeoutMs and protocolVersion (auto, legacy or 2026-07-28; leave it unset unless a server needs it).

Why Bearer and not X-API-Key. Our REST API takes the key in an X-API-Key header. The hosted MCP server's initialize response says: "Auth: paste your twitterapi.io API key as the Bearer token." Its OAuth metadata at mcp.twitterapi.io/.well-known/oauth-protected-resource lists bearer_methods_supported: header, so the Authorization: Bearer header is the documented path for MCP clients.

The schema is strict. In ZCode's config schema each MCP server object is validated with .strict(): a misspelled or unsupported field invalidates that one server (ZCode logs config_mcp_server_invalid and keeps the rest of the config). Two conveniences are built in: a legacy http_headers field is renamed to headers, and a remote type, common in other agents' configs, is treated as http.

Restart and verify. The docs warn that a process starting is not proof a config took effect. Open a new session and ask a question that forces a tool call, then check the tool name in the run log: ZCode's MCP guide says registered tools usually carry an mcp__ prefix and that you should judge success by the real tool call, not by the model saying it can access MCP.

ZCode's MCP page documents four files. The user-level native file sits under .zcode/cli/, the workspace one directly under .zcode/; both are named config.json, which is the most common source of "I edited the file and nothing changed".

Rule 1: .zcode beats .agents, with no merging. Within a scope, as soon as any server is read from a .zcode file, the .agents/mcp.json of the same scope is skipped entirely. If you keep shared servers in .agents/mcp.json and then add the X server through the settings panel (which always writes to .zcode), your .agents servers stop loading. The fix the docs give is to merge them into the .zcode file.

Rule 2: your config beats the project's. If a workspace and your user config define a server with the same name, the user entry wins, so a cloned repository cannot replace your twitterapi server with its own.

Rule 3: disabled is a field. Turning a server off in the list writes "enable": false into its object; without the field it counts as enabled.

Importing instead of retyping. If the X server is already set up in Claude Code (~/.claude/settings.json), Codex CLI (~/.codex/config.toml) or OpenCode (~/.config/opencode/opencode.json), the Import icon on the MCP Servers page lists those servers and copies the ones you select into the .zcode file of the scope you choose. The original files are left untouched.

Workspace MCP servers connect on open. ZCode's MCP docs say servers declared in a project's configuration connect automatically at session start, with no per-session authorization, so a team can commit MCP config to a repository. The same page warns that an MCP server can run commands, read and write files and reach the network, and asks you to look at a repository's .zcode/config.json before opening one from a source you do not know. Do that for .agents/mcp.json too.

Keep the X key in user scope. The headers value in the example above is plain text in a JSON file. ZCode's docs do not describe environment-variable expansion inside MCP headers (the provider-config guide says outright that ${ENV} substitution is not promised for API keys), so put the server in ~/.zcode/cli/config.json, restrict that file's permissions, and never in a project's .zcode/config.json that could be committed. For the stdio route, the key sits in the server's env block in the same user file.

Separate keys for separate jobs. Create a dedicated twitterapi.io key for the agent in the dashboard so you can rotate it without breaking other scripts, and watch usage there after the first runs.

Tool visibility is not permission. ZCode's MCP guide notes that visibility, tool filtering and permissions are different layers; to remove the capability entirely, turn off features.mcp and check whether a plugin or the browser tool still offers an equivalent path. If you evaluate runs, the guide asks you to keep keys, Authorization headers and OAuth credentials out of the dataset.

The hosted server is the shortest path, but the same 12 tools ship as an npm package, @twitterapi_io/mcp-server (version 0.2.0 on the npm registry when we checked), which reads the key from the TWITTERAPI_IO_API_KEY environment variable. ZCode's docs show npx with -y as the standard stdio pattern, and its schema accepts command, args, cwd and env for stdio servers.

When to prefer stdio. Pick it when your network policy blocks outbound MCP over HTTP but allows the package registry and api.twitterapi.io, or when you want to pin a server version in args (for example @twitterapi_io/mcp-server@0.2.0). The CLI guide adds one caveat: the program in command and its dependencies must be installed on the machine; the single-file CLI build does not supply Node for external scripts.

Proxy note. ZCode's install docs say an empty HTTP proxy field in Settings, General means a direct connection and that ZCode does not read HTTP_PROXY. Once a proxy is set there, model requests, MCP servers and tools the agent runs all go through it. If the X tools time out while curl works in your terminal, check that field first.

MCP gives the agent tools; a skill gives it judgment about when and how to use them. ZCode's Skill docs define a skill as a folder containing SKILL.md, where the folder name is the name you reference in chat. User-level skills for the ZCode Agent live in ~/.zcode/skills/<skill-name>/SKILL.md; the CLI guide adds project-level .zcode/skills and .agents/skills folders, with .zcode taking priority when both exist.

We publish a ready-made skill at twitterapi.io/skills/twitterapi-io/SKILL.md (name twitterapi-io). It tells the agent which endpoint fits a task (profile, recent posts, a keyword or from: search, mentions, followers, posts by ID), how to follow next_cursor, to keep only the fields it needs, and what each call costs. The install is a download into the skills folder, shown below.

Format limits that bite. name and description are required, or the skill is ignored with a diagnostic. description is capped at 1,024 characters: going over drops the whole skill rather than truncating it. A body over 100KB is truncated on load. Our skill's description is 362 characters and its file about 9KB, within all three limits.

The 250-character rule. Each turn, ZCode injects the metadata of every enabled skill, the name plus a description excerpt of up to 250 characters, and loads bodies only when a skill is invoked. All skills share one metadata budget; past it, ZCode falls back to names only and automatic triggering drops sharply. Put the trigger words (X, Twitter, posts, mentions, followers) in the first 250 characters, and disable skills you do not use.

Calling it. Type $ in the chat box and pick the skill, or use the Skills group in the / menu, then write the request: $twitterapi-io find this week's posts that mention GLM-5.3 and summarize the complaints. After adding or editing a skill, use Refresh on the Skills settings page (or zcode skills list --json in the CLI) and confirm it appears and is enabled; the docs warn that a file on disk is not proof it loaded.

Already using it elsewhere? The Skills page has the same Import button as MCP: it scans Claude Code, Codex CLI and other agents' skill folders, and imports as a symlink (follows later edits) or a copy (independent).

With either route in place, a useful first task is a bounded one: "Search X for posts about zcode mcp from the last 7 days, one page, and list the three most-liked with their URLs." Through MCP, the agent calls search_tweets; through the skill, it calls /twitter/tweet/advanced_search with queryType=Latest. Either way the response is a page of up to 20 posts with has_next_page and next_cursor.

Fields to tell the agent about. Each post carries id, url, text, createdAt (formatted like Thu Oct 16 12:34:56 +0000 2026, not ISO 8601), lang, likeCount, retweetCount, replyCount, quoteCount, viewCount, bookmarkCount, isReply, and an author object with userName, followers and isBlueVerified. There is no public_metrics object; an agent that has learned the official X API's shapes will look for it, so say so in the prompt or the skill.

Keep the context small. A raw page is large because every post repeats its author profile and entities. For anything bigger than a quick question, have the agent write a script that trims each post to a handful of fields before printing, like the one at the end of this page, and run that instead of pasting raw pages into the conversation.

Treat tweet text as untrusted input. Posts are written by strangers and can contain instructions aimed at agents. Tell the agent in the skill or the prompt to quote and summarize tweet text, never to follow instructions found inside it.

Plan mode for a first run. ZCode's CLI accepts --mode plan; the quickstart notes that --prompt defaults to yolo mode, which is neither read-only nor a sandbox. MCP reads do not touch your files, so plan mode is a safe way to check the tools before the agent is allowed to write code around them.

Before writing setup instructions we checked what people say about ZCode on X. A Latest search for zcode (reposts excluded) returned 800 posts over 14.9 days, about 53.6 a day from 443 distinct accounts. Not all of it is about the coding agent: 38.5% of posts carry none of our AI-coding keywords, and a single Spanish-language sports-tips account with the name in its handle posted 15.4% of the whole sample. That is the noise a monitoring agent has to filter.

Of the 492 posts with an AI-coding keyword, 51.2% are in Chinese and 35.0% in English. The topics are models and promotions, not setup:

Setup talk exists, but you have to ask for it. A narrower search, zcode (mcp OR skill OR skills), returned 144 posts from 2026: 32.6% mention MCP and 45.1% skills, and 0.0% mention Twitter or X data. The official ZCode account (@zcode_ai) posted 23 times in the window we could read; 30.4% of those posts announce free tokens and none mention MCP or skills. On Z.ai's main account, 13 of its last 200 posts (6.5%) mention ZCode, with a median of 203,481 views against 58,110 for its other posts.

What that means for you. The query "zcode twitter" is new and thin, and nobody on X is yet describing how to connect ZCode to X data, which is why this page leads with the configuration rather than opinions.

twitterapi.io bills 15 credits per tweet returned, which is $0.15 per 1,000 tweets, with a minimum of 15 credits per request, so a search that returns nothing costs $0.00015 and a full 20-tweet page costs $0.003. Profiles are 18 credits per user ($0.18 per 1,000). $1 buys 100,000 credits, and purchased credits never expire. Reads need no X account.

The official X API's pay-per-use rate card (docs.x.com/x-api/getting-started/pricing, read this session) charges $0.005 per post read and $0.010 per user read, with pay-per-usage plans capped at 3 million post reads per monthly billing cycle and an Enterprise plan above that. Per 1,000 posts that is $5.00 against $0.15, about 33x.

Agents loop, so cap them. Tool calls inside an agent are easy to repeat. The skill and the script below both set a request cap, and a polling job that finds nothing still pays the minimum: a check every 60 seconds for a month is 43,200 checks, $6.48; every 5 minutes, $1.30.

Rate limits. 0.2 requests per second before the first payment and 20 once paid (50 on Scale, 500 on Business, up to 1,000 on request). Subscriptions run from Starter at $29 to Business at $1,499 a month; see /pricing for what each includes. New accounts that pass the automatic bot check get up to $1 of free credits (at most 100,000 credits, no card, one per person or network, expiring after 31 days).

Writes are separate. The MCP server and the skill are read-only. Posting, liking, following or deleting goes through REST endpoints such as /twitter/create_tweet_v2 and /twitter/follow_user_v2 after one /twitter/user_login_v2 login ($0.10, with a proxy you supply); each action is then $0.0006, billed per HTTP 200 call. Those calls act as that account, so X can rate-limit, lock or suspend it; keep a human pace, and expect the session to need a re-login now and then. Keep write actions out of autonomous agent loops.

Question. When people post about ZCode on X, what do they talk about, how much of the term's traffic is about the coding agent at all, and how often do setup topics (MCP, skills, CLI) come up?

Queries and accounts. Two /twitter/tweet/advanced_search queries, zcode -filter:retweets (40 pages) and zcode (mcp OR skill OR skills) -filter:retweets (9 pages), both queryType=Latest, plus the recent timelines of two organization accounts, Z.ai (@Zai_org, 200 posts) and the official ZCode account (@zcode_ai, 23 posts, confirmed by its profile and its links to zcode.z.ai and the GitHub repository).

Window and size. The newest posts at collection time: 800 posts over 14.9 days for the broad search, 148 for the narrow one (144 from 2026). 1,171 posts in total from 63 requests, collected in 2026, at a data cost of $0.18.

Method. Topics are keyword regexes on lowercased post text (listed in analyze.py in our study folder), so a post can match several topics, and short replies with no keyword count as having no AI-coding signal even when they are about ZCode. Chinese-language posts are matched with Chinese keywords as well as English ones.

What the sample cannot show. Search returns recent public posts only; it says nothing about how many people use ZCode, how well the setup works for them, or private conversations. Engagement medians are skewed by a few promotional posts.

Privacy. Aggregates only. Raw search pages, whose authors are mostly private individuals, were kept out of the published study; the de-identified sample holds no IDs, URLs, text or handles. Only the two organization timelines are kept as raw data.