Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Podio MCP Server show me my open Podio tasks due this week"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A Model Context Protocol (MCP) server for Podio. Inspect APIs, authenticate, manage items/tasks/apps, and generate TypeScript field configs from Cursor, Claude Desktop, or any MCP-compatible client.
Consolidated Podio tools — items, apps/spaces, tasks, communication, search, metadata, system
Generic API caller — call any catalogued Podio endpoint via callPodioApi
OAuth / app-token auth — organization- and app-level tokens
API catalog — browse and search Podio endpoints
HTTP/SSE mode — optional remote access (Docker / npm run start:http)
Related MCP server: Taskade MCP Server
Node.js 18+
Podio account with API access
An MCP client (e.g. Cursor, Claude Desktop)
Add to your MCP client config (e.g. Cursor .cursor/mcp.json):
{
"mcpServers": {
"podio-developer-mcp": {
"command": "npx",
"args": ["-y", "@phasesdk/mcp-server-for-podio"]
}
}
}Create podio.config.json in the working directory the client uses for the server (often your project root):
cp podio.config.json.example podio.config.json
# edit clientId, clientSecret, appsRestart the client, then verify with podio_system operation ping or get_config_status.
git clone https://github.com/phases/mcp-server-for-podio.git
cd mcp-server-for-podio
npm install
npm run buildPoint the client at the built entry:
{
"mcpServers": {
"podio-developer-mcp": {
"command": "node",
"args": ["/absolute/path/to/mcp-server-for-podio/dist/index.js"]
}
}
}npm run build
npm run dev
npm start
npm run lint
npm run formatHTTP mode (landing page + SSE):
npm run start:http
# open http://localhost:3016/Tool | Description |
| Get, create, update, delete, filter items; field history / revisions |
| Orgs, spaces, apps, streams |
| Get, list, create, update, complete tasks |
| Comments, statuses, notifications, tags, subscriptions |
| Global / app search and contacts |
| API catalog, app fields, app relations (incl. deep / CRM map), forms, views |
|
|
| Call any endpoint from the bundled API catalog |
Most tools take an operation enum. Example: podio_system with { "operation": "ping" }.
mcp-server-for-podio/
├── src/ # MCP server and tools
├── data/catalog/ # Podio API catalog (required at runtime)
├── dist/ # Compiled output
├── docs/ # Extra documentation
└── index.html # HTTP landing pageSee CONFIGURATION.md. Required: clientId, clientSecret. Optional: username, password, apps[].
Secrets live in podio.config.json (gitignored). Never commit that file.
Use this when clients connect over a URL (SSE), not local npx/stdio.
Endpoints
Path | Purpose |
| Landing page ( |
| MCP SSE session |
| MCP messages |
| Health check |
Run locally in HTTP mode
npm ci && npm run build
PORT=3016 BIND_ADDRESS=0.0.0.0 node dist/index.js
# or: npm run start:httpCreate podio.config.json in the process working directory (copy from podio.config.json.example). Bind-mount it for Docker.
Docker
docker build -t mcp-server-for-podio .
docker run --rm -p 3016:3016 \
-v "$PWD/podio.config.json:/app/podio.config.json:ro" \
-e PORT=3016 \
mcp-server-for-podioRemote client config
{
"mcpServers": {
"podio-developer-mcp": {
"url": "https://your-host.example/sse"
}
}
}Production reverse proxy, TLS, systemd/PM2: see DEPLOYMENT.md.
Package is ready to ship. From a clean tree after npm run build:
GitHub. The published branch is main on phases/mcp-server-for-podio. Do not push master.
git remote add github git@github.com:phases/mcp-server-for-podio.git # first time only
git push -u github HEAD:mainnpm (logged in as a member of the phasesdk org):
npm whoami
npm publish --access publicBump version in package.json before republishing. prepublishOnly runs tsc automatically. Published tarball includes dist/, data/, index.html, and the example config (see files in package.json).
In HTTP mode, GET / serves index.html with connect instructions.
Deployment — reverse proxy, TLS, systemd/PM2
MIT
Issues and PRs welcome once the GitHub repo is live: phases/mcp-server-for-podio.
Call any Podio API endpoint from the catalog. Use getApiDetails to see available endpoints and their parameters. Example: "call the items-get endpoint with item_id 123"
| Name | Required | Description | Default |
|---|---|---|---|
| appId | No | App ID for app-level authentication (required if useAppAuth is true) | |
| appToken | No | App token for app-level authentication (required if useAppAuth is true) | |
| bodyParams | No | Body parameters for POST/PUT requests (e.g., { "fields": {...}, "text": "Task description" }) | |
| endpointId | Yes | The catalog endpoint ID (e.g., "items-get", "apps-list", "users-me"). Use getApiDetails to find endpoint IDs. | |
| pathParams | No | Path parameters as key-value pairs (e.g., { "item_id": 123, "app_id": 456 }) | |
| useAppAuth | No | Whether to use app-level authentication instead of organization-level (default: false) | |
| queryParams | No | Query parameters as key-value pairs (e.g., { "limit": 10, "completed": true }) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden for a generic endpoint dispatcher that may perform reads or writes. It does not disclose authentication behavior, side effects, rate limits, error handling, or the fact that different endpoints may have very different safety profiles.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is short, front-loaded with the core purpose, and immediately follows with the discovery prerequisite and a concrete example. Every sentence contributes to understanding how to use the tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The tool is complex: seven parameters, nested objects, no annotations, no output schema, and dynamic endpoint-specific behavior. The description gives the essential getApiDetails discovery path, and the schema richly documents parameters, but it omits response shape, authentication implications, and mutation risk.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the parameter details are already well documented in the schema. The description's example reinforces endpointId and pathParams usage, but it does not add meaning beyond the schema for bodyParams, queryParams, or app-level authentication.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource: calling a Podio API endpoint from the catalog. It distinguishes itself as a generic catalog dispatcher, though 'any endpoint' remains broad and does not clarify the relationship to the domain-specific sibling tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It tells the agent to use getApiDetails to discover available endpoints and their parameters, and gives a concrete usage example. However, it does not explain when to choose this generic dispatcher over the higher-level podio_* sibling tools or when not to use it.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage Podio Spaces, Apps, and Organizations, including activity streams.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name (for create_space) | |
| appId | No | App ID | |
| limit | No | Limit | |
| orgId | No | Organization ID | |
| offset | No | Offset | |
| privacy | No | Privacy (for create_space) | |
| spaceId | No | Space ID | |
| operation | Yes | The operation to perform |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it never says that 12 of the 13 operations are reads and only create_space mutates state, nor does it mention permissions, pagination semantics, or response shape. 'Manage' implies broad mutation, which misrepresents a mostly read-only dispatcher.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no waste, but its brevity comes from under-specification rather than economy; for a 13-operation dispatcher this is too terse to be useful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no annotations, no output schema, and a 13-value operation enum, the description should enumerate operations or at least group them by read vs. write and by resource. Instead it offers one generic sentence, leaving the agent substantially under-equipped to invoke this tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is nominally 100%, but the per-parameter descriptions are tautological ('App ID' for appId, 'Limit' for limit), and the critical mapping of which parameters apply to which of the 13 operations is documented nowhere. The description adds no parameter meaning at all, leaving the agent to guess that appId belongs to get_app and spaceId to list_space_apps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names the resource families (Spaces, Apps, Organizations, activity streams), which does scope it away from podio_items/podio_tasks siblings, but the verb 'Manage' is vague and none of the 13 supported operations are mentioned. An agent cannot tell from the description alone whether this tool reads, creates, or does both.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus podio_metadata, podio_search, or callPodioApi, and no guidance on how to choose among the 13 operations. The only signal is the operation enum in the schema, which the description never references.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage comments, statuses, notifications, tags, and subscriptions.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Tags list | |
| refId | No | ||
| value | No | Comment or status text | |
| viewed | No | ||
| fileIds | No | ||
| refType | No | ||
| starred | No | ||
| statusId | No | ||
| commentId | No | ||
| operation | Yes | Communication operation | |
| externalId | No | ||
| notificationId | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden of behavioral disclosure. 'Manage' implies mutation, but the description does not mention side effects, permissions, reversibility, or which operations are destructive versus read-only.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single front-loaded sentence with no filler, but it is under-specified rather than appropriately concise for a complex multi-operation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
A 17-operation, 12-parameter tool with no output schema and no annotations needs substantial description to be callable correctly. One sentence naming resource categories is completely inadequate for that complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 25% across 12 parameters, and the description adds no parameter meaning at all. Critical fields like refId, refType, commentId, notificationId, and the operation enum are left entirely to the schema, so the description fails to compensate for the coverage gap.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
It names the communication domain and lists the resources involved (comments, statuses, notifications, tags, subscriptions), but the verb 'Manage' is vague and does not clarify the 17 distinct operations or distinguish this tool from sibling domain tools.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It provides no guidance on when to use this tool versus alternatives like podio_items or podio_tasks, nor any prerequisites, context, or exclusions for the individual communication operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage Podio items: fetch, create, update, delete, and filter items in apps.
| Name | Required | Description | Default |
|---|---|---|---|
| tags | No | Tags (for create, update) | |
| appId | No | The ID of the app (for create, filter, delete-auth) | |
| hooks | No | Enable hooks (for create, default: true) | |
| limit | No | Result limit (for filter) | |
| fields | No | Field values (for create, update) | |
| itemId | No | The ID of the item (for get, update, delete, get_field_value, get_revisions, etc.) | |
| offset | No | Pagination offset (for filter) | |
| sortBy | No | Sort field (for filter) | |
| fieldId | No | The ID of the field (for get_field_value) | |
| fileIds | No | File IDs to attach (for create) | |
| filters | No | Filters (for filter) | |
| appToken | No | App token for app-level auth (optional) | |
| revision | No | Revision number (for get_revision) | |
| sortDesc | No | Sort descending (for filter) | |
| operation | Yes | The operation to perform on items | |
| externalId | No | External ID (for create) | |
| itemFields | No | Optional comma-separated field external IDs to include (for get) | |
| revisionTo | No | Ending revision (for get_revision_diff) | |
| revisionFrom | No | Starting revision (for get_revision_diff) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It mentions delete and create but never says whether deletes are permanent, whether hooks fire (the schema exposes a `hooks` flag), what auth is required, or what happens on update to unspecified fields. Only the operation list hints at behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with zero filler. It is efficient, though for a 19-parameter mega-tool it borders on undersized rather than being wasteful.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 10 operations, 19 parameters, no annotations, and no output schema, the description omits the revision/history operations (get_field_value, get_revisions, get_revision, get_revision_diff, get_field_history) entirely and gives no per-operation parameter or return expectations. An agent must reverse-engineer operation semantics from the schema alone.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% and individual params already carry per-operation hints ("for create, update"), so the schema does the heavy lifting. The description adds no parameter meaning beyond what's structured, which is the baseline-3 case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb-plus-resource ("Manage Podio items") and enumerates core operations (fetch, create, update, delete, filter) scoped to apps, which separates it from siblings like podio_tasks or podio_metadata. However, it only names 5 of the 10 operations the schema's enum supports, and uses "fetch" where the schema says "get", so the scope is described imprecisely.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to choose this tool over siblings such as podio_search (which likely covers item filtering) or callPodioApi. There are no prerequisites, no exclusions, and no conditions that select among the 10 operations.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Explore Podio API, app fields, app relations (direct or deep to max depth), forms, and views.
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | ||
| type | No | ||
| apiId | No | ||
| appId | No | ||
| group | No | ||
| fields | No | ||
| formId | No | ||
| viewId | No | ||
| appName | No | ||
| filters | No | ||
| keyword | No | ||
| spaceId | No | Space ID for list_crm_relation_map (default: 1404261 CRM) | |
| operation | Yes | Metadata operation | |
| withDrillDown | No | Include one level drill-down for list_crm_relation_map (default: true) |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the full behavioral burden, but it frames the tool as exploration while the operation enum includes mutations like submit_form and create_view. It discloses no permissions, side effects, reversibility, or operation-specific behavior beyond a brief mention of relation depth.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence with the domain front-loaded. However, it is too terse and unstructured for a tool with 14 distinct operations, offering no grouping or operation-level cues.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 14 operations, 14 parameters, no annotations, no output schema, and low schema coverage, the description is far from complete. It gives only a high-level domain list and omits required parameter mappings, mutation warnings, and return behavior.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 21%, and the description gives no mapping of parameters to the 14 operations. It hints at 'direct or deep to max depth' for relations, but leaves most parameters such as appId, formId, viewId, filters, and fields unexplained.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description lists resource areas (Podio API, app fields, relations, forms, views) but uses the vague verb 'Explore' and does not clearly state the operation-level purpose. It also fails to distinguish this metadata tool from siblings such as podio_apps_spaces or podio_search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit guidance on when to use this tool versus alternatives, no exclusions, and no prerequisites. Usage is only implied by the list of resource types.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search across Podio for items, tasks, statuses, contacts, etc.
| Name | Required | Description | Default |
|---|---|---|---|
| appId | No | ||
| limit | No | ||
| orgId | No | ||
| query | No | Search term | |
| refType | No | ||
| spaceId | No | ||
| contactId | No | ||
| operation | Yes | Search operation |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden, yet it says nothing about permissions, pagination, result limits, or how the operation modes behave. 'Search' implies a read, but nothing beyond that is disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence with no wasted clauses, but the brevity comes at the cost of under-specification; 'etc.' signals imprecision rather than conciseness.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a tool with 8 parameters including a five-value operation enum (global, app, contacts, get_contact, list_contacts) plus no annotations and no output schema, the description is inadequate. It never explains the operation modes, which are the primary driver of how the tool is invoked.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With only 25% schema description coverage across 8 parameters, the description needs to compensate but does not. The listed content types loosely echo the refType/operation enum values but explain none of the parameters (appId, orgId, spaceId, contactId, limit) or the meaning of the five operation modes.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a clear verb ('Search') and resource ('across Podio'), and lists example content types (items, tasks, statuses, contacts). However, it does not differentiate this tool from siblings like podio_items or podio_tasks, and the trailing 'etc.' leaves the scope fuzzy.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this search tool versus the topic-specific siblings (podio_items, podio_tasks, podio_communication) or how the 'operation' modes differ. An agent must infer the selection criteria entirely.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
System tools: ping, config, files, hooks, batch, and calendar.
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | ||
| type | No | ||
| appId | No | ||
| items | No | ||
| refId | No | ||
| dateTo | No | ||
| fileId | No | ||
| hookId | No | ||
| refType | No | ||
| spaceId | No | ||
| appToken | No | ||
| dateFrom | No | ||
| operation | Yes | System operation | |
| outputPath | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It lists categories but says nothing about destructive operations like delete_file or delete_hook, hook verification behavior, batch execution semantics, permission requirements, or what any operation returns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single short sentence with no wasted words, but for a 12-operation, 14-parameter system tool it is severely under-specified rather than appropriately concise. It is not structured to help the agent select among operations or understand the parameter surface.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 12 enum operations, 14 parameters, no annotations, no output schema, and very low schema description coverage, the description is far too thin. An agent would have to infer operation behavior, required parameters per operation, mutation risks, and return formats entirely from the schema enum.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is only 7%, and the sole documented parameter is the generic 'operation' field. The description does not explain the 13 other parameters, does not map parameters to specific operations, and provides no meaning for fields such as fileId, hookId, refType, appToken, outputPath, or dateFrom/dateTo.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names six system operation families (ping, config, files, hooks, batch, calendar), which gives a broad sense of scope beyond the tool name alone. However, it does not state actual verbs or explain what any operation does, and it does not clearly differentiate this tool from the domain-specific siblings such as podio_items or podio_apps_spaces.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention the sibling tools at all, nor does it explain whether system-level file/hook/calendar operations should be routed here rather than through podio_items, podio_apps_spaces, or callPodioApi.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Manage Podio tasks: fetch, create, update, and complete tasks.
| Name | Required | Description | Default |
|---|---|---|---|
| text | No | Task text/description | |
| appId | No | App ID (for list) | |
| dueOn | No | Due date (YYYY-MM-DD HH:MM:SS) | |
| orgId | No | Org ID (for list) | |
| refId | No | Reference ID | |
| status | No | Task status | |
| taskId | No | Task ID | |
| private | No | Private task | |
| refType | No | Reference type | |
| spaceId | No | Space ID (for list) | |
| completed | No | Filter by completed | |
| operation | Yes | The operation to perform on tasks | |
| responsible | No | Responsible user ID |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It does not explain permission requirements, whether completing a task is irreversible, how listing is scoped by appId/orgId/spaceId, or what the response includes; it only restates the broad operations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
It is a single, front-loaded sentence with no wasted framing. The only weakness is that it is a generic capability list rather than a structured summary of the multi-operation tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 13-parameter, multi-operation mutation tool with no annotations and no output schema, the description is too thin. It does not explain operation-specific parameter requirements or return behavior, leaving the agent to infer which parameters apply to get, list, create, update, and complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents all 13 parameters including the operation enum. The description adds no parameter-level meaning beyond what is already in the schema, which is the baseline 3 case.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific resource (Podio tasks) and a clear set of operations (fetch, create, update, complete). It is distinguishable from siblings such as podio_items or podio_apps_spaces because it is scoped to tasks, though it does not explicitly mention the 'list' or 'get' operation names used in the enum.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no guidance on when to use this tool versus alternatives such as callPodioApi or other Podio sibling tools. The description lists capabilities but does not state prerequisites, exclusions, or operation-selection context.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.0callPodioApipodio_apps_spacespodio_communicationpodio_itemspodio_metadatapodio_searchpodio_systempodio_tasksScored across 8 tools
The tools are mostly separated by Podio domain (items, tasks, search, communication, metadata), so an agent can usually pick the right category. However, callPodioApi overlaps with every other tool as a generic catch-all, and boundaries such as items-filtering versus search are somewhat loose.
Seven tools follow a clear podio_<domain> snake_case convention, but callPodioApi breaks the pattern with camelCase and no podio_ prefix. The set remains readable, but the convention is not fully consistent.
Eight tools is a well-scoped count for a broad API like Podio, with each major domain area represented without excessive fragmentation. The domain-bundle approach keeps the count manageable while still exposing the main capabilities.
The surface covers the major Podio areas: items, apps/spaces/organizations, tasks, communication, search, metadata, and system utilities. The generic callPodioApi tool also provides an escape hatch for any endpoint not explicitly bundled, so there are no obvious dead ends.
Read and write Mission Control state via MCP — projects, tasks, subtasks, templates, status updates.
Generate a typed SDK, CLI, and MCP server from any OpenAPI or GraphQL spec, and keep them current.
Manage Pipefork API projects, drafts, connections, secrets, and deployments through MCP.
Product Hunt MCP — wraps the Product Hunt GraphQL API v2 (api.producthunt.com)