{"service":"Podio External MCP Server","version":"2.0.0","description":"MCP server exposing Podio API tools for integration with ChatGPT, Copilot Studio, and other MCP-compatible clients.","transport":"Streamable HTTP (POST /mcp)","mcp_endpoint":"/mcp","authentication":{"type":"oauth2","flow":"authorization_code","authorization_url":"https://mcp.podio.com/oauth/authorize","token_url":"https://mcp.podio.com/oauth/token","discovery_url":"https://mcp.podio.com/.well-known/oauth-authorization-server","description":"OAuth2 Authorization Code flow via Podio. Redirect users to /oauth/authorize to grant access. The obtained Bearer token is sent with each MCP request via the Authorization header."},"tools":[{"name":"update_item","description":"Update specific fields on an existing Podio item. Only include fields you want to change — other fields remain untouched. IMPORTANT: Field keys MUST be Podio external_ids (lowercase, e.g. \"property_title\"), NOT display labels (e.g. \"Property Title\"). If you do not know the external_ids, call get_app with the app_id of this item's app to retrieve them. Field value formats: (1) Date fields MUST use the object form: {\"start\": \"YYYY-MM-DD HH:MM:SS\"} or {\"start\": \"YYYY-MM-DD HH:MM:SS\", \"end\": \"YYYY-MM-DD HH:MM:SS\"} for a range. (2) Phone/email entries MUST have a non-null type string (e.g. \"work\"). (3) Category fields expect an array of numeric option IDs (e.g. [1]), not the label string. (4) Money fields use {\"currency\": \"USD\", \"value\": 49.99}. (5) App-reference fields use [{\"app_item_id\": 12345}]. (6) Image/file fields use an array of file IDs: [file_id_1, file_id_2].","inputSchema":{"type":"object","properties":{"item_id":{"type":"number","description":"The ID of the Podio item to update"},"fields":{"type":"object","description":"Object mapping field external_ids to new values. Only include fields to change. Keys MUST be external_ids (lowercase with underscores), NOT display labels. Use get_app to find external_ids. Example: {\"title\": \"Updated name\", \"status\": [2], \"due_date\": {\"start\": \"2026-06-01 00:00:00\"}}"},"tags":{"type":"array","items":{"type":"string"},"description":"Optional: Replace ALL tags on the item with these tags. Only include if the app has tags enabled."},"revision":{"type":"number","description":"Optional: Revision number for optimistic locking. If the item's current revision does not match this value, the update is rejected — preventing silent overwrites of concurrent edits. Retrieve the current revision from get_item."},"silent":{"type":"boolean","description":"Optional: When true, the update does not trigger hooks, stream entries, or notifications (default: false)."}},"required":["item_id","fields"]}},{"name":"add_comment","description":"Add a comment to a Podio item.","inputSchema":{"type":"object","properties":{"item_id":{"type":"number","description":"The ID of the Podio item to comment on"},"text":{"type":"string","description":"The comment text content"}},"required":["item_id","text"]}},{"name":"get_item","description":"Get a single Podio item by its ID. Returns a detail-level shape with all decoded field values, created/modified dates, tags, and author metadata.","inputSchema":{"type":"object","properties":{"item_id":{"type":"number","description":"The unique ID of the Podio item to retrieve"}},"required":["item_id"]}},{"name":"get_items","description":"Get items from a Podio app with optional filtering, sorting, and pagination. Pass \"filters\" to narrow results by field values (absorbs the former filter_items tool). Returns a paginated list of compact items with decoded field values. Use get_item for full details on a specific item.","inputSchema":{"type":"object","properties":{"app_id":{"type":"number","description":"The ID of the Podio app to get items from"},"filters":{"type":"object","description":"Optional filter conditions. IMPORTANT: Keys MUST be field external_ids (e.g. \"status\", \"priority-2\"), NOT human-readable labels (e.g. \"Status\", \"Priority\"). Call get_app first to discover external_ids and category/question option IDs.\nValues depend on field type:\n• text: NOT filterable — text fields cannot be used in filters; use search_globally instead\n• category/question: [1, 2] — array of INTEGER option IDs (NOT string labels like \"Done\"). Get option IDs from get_app.\n• date: {\"from\": \"2025-01-01\", \"to\": \"2025-12-31\"} — either key may be omitted for an open-ended range (e.g. {\"from\": \"2025-01-01\"} is valid). Supports relative dates (+1d, -7d, +1w, +1m, +1y) or absolute YYYY-MM-DD strings\n• number/money: {\"from\": 10, \"to\": 100} — BOTH \"from\" AND \"to\" keys are REQUIRED; set a value to null for an open-ended bound (e.g. {\"from\": 10, \"to\": null}); at least one must be non-null; values MUST be numbers (not strings)\n• calculation: {\"from\": ..., \"to\": ...} — BOTH \"from\" AND \"to\" keys are REQUIRED (null for open-ended); value type depends on return_type (numbers for numeric calculations, YYYY-MM-DD strings for date calculations; text-returning calculations are NOT filterable)\n• progress: {\"from\": 0, \"to\": 50} — BOTH \"from\" AND \"to\" keys are REQUIRED (null for open-ended); integer values 0-100\n• duration: {\"from\": 0, \"to\": 8} — BOTH \"from\" AND \"to\" keys are REQUIRED (null for open-ended); values are in HOURS (decimals allowed, e.g. 1.5 = 90 min)\n• app reference: [item_id_1, item_id_2] — array of integer item IDs (null matches items with no reference)\n• contact: [profile_id_1, profile_id_2] — array of integer PROFILE IDs (not item_id; null matches items with no contact)\nCommon mistakes: (1) using field labels instead of external_ids, (2) passing string labels for category/question filters instead of integer IDs, (3) wrapping text values in {\"from\": ...} — text fields are not filterable, (4) using strings instead of numbers in range filter values."},"limit":{"type":"number","description":"Maximum number of items to return (default: server-configured via MCP_MAX_ITEMS_PER_PAGE, max: 500)"},"offset":{"type":"number","description":"Offset for pagination (default: 0). Prefer using cursor instead."},"cursor":{"type":"string","description":"Opaque pagination cursor from a previous response's nextCursor. Takes precedence over offset."},"sort_by":{"type":"string","description":"Field external_id or \"created_on\", \"last_edit_on\" to sort by"},"sort_desc":{"type":"boolean","description":"Sort descending if true (default: true)"}},"required":["app_id"]}},{"name":"get_app","description":"Get details about a Podio app including its configuration, field definitions (external_ids, labels, types), and metadata. For category/question fields, option IDs and labels are included — use these when building filter conditions for get_items or get_app_summary.","inputSchema":{"type":"object","properties":{"app_id":{"type":"number","description":"The ID of the Podio app to get details for"}},"required":["app_id"]}},{"name":"get_apps_in_space","description":"Get all apps in a Podio workspace (space). Returns a list of apps with their IDs, names, and configurations.","inputSchema":{"type":"object","properties":{"space_id":{"type":"number","description":"The ID of the Podio workspace/space to list apps from"}},"required":["space_id"]}},{"name":"get_space","description":"Get details about a Podio workspace (space) including name, privacy settings, and organization info.","inputSchema":{"type":"object","properties":{"space_id":{"type":"number","description":"The ID of the Podio workspace/space to get details for"}},"required":["space_id"]}},{"name":"get_organizations","description":"Get all Podio organizations the authenticated user is a member of. Returns org IDs, names, and metadata.","inputSchema":{"type":"object","properties":{}}},{"name":"get_spaces_in_organization","description":"Get all workspaces (spaces) in a Podio organization. Returns space IDs, names, and privacy settings.","inputSchema":{"type":"object","properties":{"org_id":{"type":"number","description":"The ID of the Podio organization to list workspaces from"}},"required":["org_id"]}},{"name":"search_globally","description":"Search Podio for items, apps, spaces, and other objects matching a text query. Scope the search to a single app (app_id) or workspace (space_id), or search across everything. Returns compact previews (type, id, title). Use get_item to fetch full details for specific items.","inputSchema":{"type":"object","properties":{"query":{"type":"string","description":"The search text to find matching objects"},"app_id":{"type":"number","description":"Restrict search to a specific app (optional)"},"space_id":{"type":"number","description":"Restrict search to a specific workspace/space (optional)"},"ref_type":{"type":"string","enum":["item","app","space","task","file","conversation","status","profile"],"description":"Filter results by object type (optional)"},"limit":{"type":"number","description":"Maximum number of results to return (default: 10)"},"offset":{"type":"number","description":"Offset for pagination (default: 0). Prefer using cursor instead."},"cursor":{"type":"string","description":"Opaque pagination cursor from a previous response's nextCursor. Takes precedence over offset."}},"required":["query"]}},{"name":"get_item_comments","description":"Get compact comment previews on a Podio item. Use get_comment(comment_id) for full text.","inputSchema":{"type":"object","properties":{"item_id":{"type":"number","description":"The ID of the Podio item to get comments for"}},"required":["item_id"]}},{"name":"get_comment","description":"Get the full basic text and attribution of a comment by ID. Full responses are limited to 16384 UTF-8 bytes including the JSON envelope. If it is too large, use cursor=\"start\" for text chunks of at most 8192 UTF-8 bytes; pass each nextCursor back until complete is true. A changed comment invalidates old cursors. No rich text or files are included.","inputSchema":{"type":"object","properties":{"comment_id":{"type":"number","description":"Positive integer ID of the comment"},"cursor":{"type":"string","description":"For oversized comments, start with \"start\", then pass the opaque nextCursor returned by get_comment."}},"required":["comment_id"]}},{"name":"get_tasks","description":"Get tasks for the authenticated Podio user. Requires at least one app_id, space_id, or org_id filter; completion status alone is not sufficient. Returns compact task previews.","inputSchema":{"type":"object","properties":{"app_id":{"type":"number","description":"Filter tasks by app ID"},"space_id":{"type":"number","description":"Filter tasks by workspace/space ID"},"org_id":{"type":"number","description":"Filter tasks by organization ID"},"completed":{"type":"boolean","description":"Filter by completion status (true = completed, false = pending)"},"limit":{"type":"number","description":"Maximum number of tasks to return (default: 20)"},"offset":{"type":"number","description":"Offset for pagination (default: 0). Prefer using cursor instead."},"cursor":{"type":"string","description":"Opaque pagination cursor from a previous response's nextCursor. Takes precedence over offset."},"sort_by":{"type":"string","description":"Sort tasks by field: \"created_on\", \"completed_on\", \"rank\", \"due_date\""},"sort_desc":{"type":"boolean","description":"Sort descending if true (default: true)"}}}},{"name":"create_item","description":"Create a new item in a Podio app with field values. IMPORTANT: Field keys MUST be Podio external_ids (lowercase, e.g. \"property_title\"), NOT display labels (e.g. \"Property Title\"). If you do not know the external_ids, call get_app first with the app_id to retrieve them from the field definitions. Field value formats: (1) Date fields MUST use the object form: {\"start\": \"YYYY-MM-DD HH:MM:SS\"} or {\"start\": \"YYYY-MM-DD HH:MM:SS\", \"end\": \"YYYY-MM-DD HH:MM:SS\"} for a range. (2) Phone/email entries MUST have a valid type string — never null. Use \"work\", \"home\", or \"other\" for email; \"work\", \"home\", \"mobile\", \"main\", \"work_fax\", \"private_fax\", or \"other\" for phone. Example phone field: [{\"value\": \"+1-555-1234\", \"type\": \"work\"}]. (3) Category/select fields expect an array of numeric option IDs (e.g. [1]), not the label string. (4) Money fields use {\"currency\": \"USD\", \"value\": 49.99}. (5) App-reference fields use [{\"app_item_id\": 12345}]. (6) Image/file field values inside fields use an array of file IDs, e.g. fields.<file_field_external_id> = [file_id_1, file_id_2]. This is distinct from the top-level file_ids parameter, which attaches already-uploaded files to the item itself. (7) Omit the tags parameter unless you know the app has tags enabled.","inputSchema":{"type":"object","properties":{"app_id":{"type":"number","description":"The numeric ID of the Podio app to create the item in"},"fields":{"type":"object","description":"Object mapping field external_ids to their values. Keys MUST be external_ids (lowercase with underscores), NOT display labels. Use get_app to find external_ids. Example: {\"title\": \"My Item\", \"status\": [1], \"due_date\": {\"start\": \"2026-03-17 00:00:00\"}, \"price\": {\"currency\": \"USD\", \"value\": 49.99}}"},"tags":{"type":"array","items":{"type":"string"},"description":"Optional: Array of tags to add to the item. Only include if the app has tags enabled."},"file_ids":{"type":"array","items":{"type":"number"},"description":"Optional: Array of already-uploaded Podio file IDs to attach to the new item."},"external_id":{"type":"string","description":"Optional: Custom external identifier for the item (useful for sync/idempotency with external systems)."},"silent":{"type":"boolean","description":"Optional: When true, the creation does not trigger hooks, stream entries, or notifications (default: false)."}},"required":["app_id","fields"]}},{"name":"get_notifications","description":"Get recent notifications for the authenticated Podio user. Returns paginated context groups, each containing compact notification previews with type, text, and timestamp. Pagination limit and cursor count groups, not individual notifications; the API does not provide a total group count.","inputSchema":{"type":"object","properties":{"limit":{"type":"number","description":"Maximum number of notification groups to return (default: 10, max: 100)"},"offset":{"type":"number","description":"Offset for pagination (default: 0). Prefer using cursor instead."},"cursor":{"type":"string","description":"Opaque pagination cursor from a previous response's nextCursor. Takes precedence over offset."},"viewed":{"type":"boolean","description":"Filter: true=viewed only, false=unviewed only, omit=all"}}}},{"name":"get_app_summary","description":"Get a compact summary of items in a Podio app. Returns app metadata and decoded item data. By default returns 5 items and omits the full field schema (use get_app to fetch schema, or pass include_schema=true). Use this to generate reports or get a quick overview of app contents. For reports covering multiple apps, keep the default limit (5) to avoid token limits.","inputSchema":{"type":"object","properties":{"app_id":{"type":"number","description":"The numeric ID of the Podio app to summarise"},"limit":{"type":"number","description":"Maximum number of items to include (default: 5, max: 500). Use a small value when summarising multiple apps.","default":5},"offset":{"type":"number","description":"Offset for pagination through items (default: 0). Prefer using cursor instead.","default":0},"cursor":{"type":"string","description":"Opaque pagination cursor from a previous response's nextCursor. Takes precedence over offset."},"sort_by":{"type":"string","description":"Field external_id to sort items by, or \"created_on\" / \"last_edit_on\" (default: \"created_on\")"},"sort_desc":{"type":"boolean","description":"Sort descending if true (default: true)","default":true},"include_schema":{"type":"boolean","description":"When true, include the full field definitions (labels, types, options) in the app metadata. Default is false to keep responses compact. Use get_app to fetch the schema separately when needed.","default":false},"filters":{"type":"object","description":"Optional filter conditions. IMPORTANT: Keys MUST be field external_ids (e.g. \"status\", \"priority-2\"), NOT human-readable labels. Call get_app first to discover external_ids and category/question option IDs.\nValues depend on field type:\n• text: NOT filterable — text fields cannot be used in filters; use search_globally instead\n• category/question: [1, 2] — array of INTEGER option IDs (NOT string labels). Get option IDs from get_app.\n• date: {\"from\": \"2025-01-01\", \"to\": \"2025-12-31\"} — supports \"from\", \"to\", or both; supports relative dates (+1d, +1w, +1m) or absolute Y-M-D strings\n• number/money: {\"from\": 10, \"to\": 100} — BOTH keys required (null for open-ended); at least one non-null; values MUST be numbers (not strings)\n• calculation: {\"from\": ..., \"to\": ...} — BOTH keys required (null for open-ended); at least one non-null; value type depends on return_type (numbers for numeric calculations, Y-M-D strings for date calculations; text-returning calculations are NOT filterable)\n• progress: {\"from\": 0, \"to\": 50} — BOTH keys required (null for open-ended); at least one non-null; integers 0-100\n• duration: {\"from\": 0, \"to\": 8} — BOTH keys required (null for open-ended); at least one non-null; values in HOURS (decimals allowed)\n• app reference: [item_id_1, item_id_2] — array of integer item IDs\n• contact: [profile_id_1, profile_id_2] — array of integer PROFILE IDs (not item_id)\nCommon mistakes: (1) using labels instead of external_ids, (2) passing string labels for category instead of integer IDs, (3) attempting to filter text fields (not supported)."}},"required":["app_id"]}},{"name":"get_space_members","description":"List members of a Podio workspace with their roles, profiles, and join dates. Returns compact member previews.","inputSchema":{"type":"object","properties":{"space_id":{"type":"number","description":"The ID of the workspace"},"limit":{"type":"number","description":"Maximum number of members to return (default: 50)","default":50},"offset":{"type":"number","description":"Offset for pagination (default: 0). Prefer using cursor instead.","default":0},"cursor":{"type":"string","description":"Opaque pagination cursor from a previous response's nextCursor. Takes precedence over offset."}},"required":["space_id"]}},{"name":"get_org_members","description":"List members of a Podio organization with optional search and pagination. Returns compact member previews.","inputSchema":{"type":"object","properties":{"org_id":{"type":"number","description":"The ID of the organization"},"query":{"type":"string","description":"Search query to filter members by name or email"},"limit":{"type":"number","description":"Maximum number of results (default: 50)","default":50},"offset":{"type":"number","description":"Pagination offset (default: 0). Prefer using cursor instead.","default":0},"cursor":{"type":"string","description":"Opaque pagination cursor from a previous response's nextCursor. Takes precedence over offset."}},"required":["org_id"]}},{"name":"get_task","description":"Get the full details of a single Podio task by its ID, including text, status, assignee, due date, and labels.","inputSchema":{"type":"object","properties":{"task_id":{"type":"number","description":"The ID of the task to retrieve"}},"required":["task_id"]}},{"name":"create_task","description":"Create a new Podio task, optionally attached to an item, space, or app.","inputSchema":{"type":"object","properties":{"text":{"type":"string","description":"Task title / text"},"description":{"type":"string","description":"Detailed task description"},"due_on":{"type":"string","description":"Due date in ISO 8601 format (e.g. \"2026-06-30T12:00:00Z\" or \"2026-06-30\")"},"responsible":{"type":"number","description":"User ID to assign the task to"},"private":{"type":"boolean","description":"Make this task private (default: false)","default":false},"ref_type":{"type":"string","enum":["item","space","app","task"],"description":"Type of object to attach the task to"},"ref_id":{"type":"number","description":"ID of the object to attach the task to (required if ref_type is provided)"},"label_ids":{"type":"array","items":{"type":"number"},"description":"Label IDs to apply to the task"}},"required":["text"]}},{"name":"update_task","description":"Update properties of an existing Podio task (text, description, due date, assignee, labels).","inputSchema":{"type":"object","properties":{"task_id":{"type":"number","description":"The ID of the task to update"},"text":{"type":"string","description":"Updated task text"},"description":{"type":"string","description":"Updated description"},"due_on":{"type":"string","description":"Updated due date in ISO 8601 format"},"responsible":{"type":"number","description":"New assignee user ID"},"private":{"type":"boolean","description":"Update private flag"},"label_ids":{"type":"array","items":{"type":"number"},"description":"Replace labels with these IDs"}},"required":["task_id"]}},{"name":"complete_task","description":"Mark a Podio task as completed.","inputSchema":{"type":"object","properties":{"task_id":{"type":"number","description":"The ID of the task to mark complete"}},"required":["task_id"]}},{"name":"list_views","description":"List all saved views (filters) for a Podio app, including their names, IDs, and whether they are private.","inputSchema":{"type":"object","properties":{"app_id":{"type":"number","description":"The ID of the app"},"include_standard_views":{"type":"boolean","description":"Include built-in views like \"All Items\", \"Recently added\" (default: false)","default":false}},"required":["app_id"]}},{"name":"get_files_on_app","description":"List files attached to items in a Podio app. Returns file metadata including name, mimetype, size, and download link.","inputSchema":{"type":"object","properties":{"app_id":{"type":"number","description":"The ID of the app whose files to list"},"limit":{"type":"number","description":"Maximum number of files to return (default: 20, max: 100)","default":20},"offset":{"type":"number","description":"Offset for pagination (default: 0). Prefer using cursor instead.","default":0},"cursor":{"type":"string","description":"Opaque pagination cursor from a previous response's nextCursor. Takes precedence over offset."}},"required":["app_id"]}},{"name":"get_files_on_space","description":"List files attached to any object in a Podio space (workspace). Returns file metadata including name, mimetype, size, and download link.","inputSchema":{"type":"object","properties":{"space_id":{"type":"number","description":"The ID of the space (workspace) whose files to list"},"limit":{"type":"number","description":"Maximum number of files to return (default: 20, max: 100)","default":20},"offset":{"type":"number","description":"Offset for pagination (default: 0). Prefer using cursor instead.","default":0},"cursor":{"type":"string","description":"Opaque pagination cursor from a previous response's nextCursor. Takes precedence over offset."}},"required":["space_id"]}},{"name":"get_labels","description":"Get all task labels (categories) available for the authenticated user. Labels are used to categorise and filter tasks.","inputSchema":{"type":"object","properties":{},"required":[]}},{"name":"create_label","description":"Create a new task label (category) for the authenticated user. Labels can then be applied to tasks via create_task or update_task.","inputSchema":{"type":"object","properties":{"text":{"type":"string","description":"Display name of the label"},"color":{"type":"string","description":"Hex colour code for the label (e.g. \"DCEEFA\"). Omit to use the Podio default."}},"required":["text"]}}]}