{"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 comments on a Podio item. Returns compact comment previews with author, text, and timestamps.","inputSchema":{"type":"object","properties":{"item_id":{"type":"number","description":"The ID of the Podio item to get comments for"}},"required":["item_id"]}},{"name":"get_tasks","description":"Get tasks for the authenticated Podio user. Can be filtered by app, workspace, organization, or completion status. 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 compact notification previews with type, text, and timestamp.","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} — supports \"from\", \"to\", or both; values MUST be numbers (not strings)\n• calculation: {\"from\": ..., \"to\": ...} — supports \"from\", \"to\", or both; value type depends on return_type (numbers for number/money calculations, Y-M-D strings for date calculations; text-returning calculations are NOT filterable)\n• progress: {\"from\": 0, \"to\": 50} — supports \"from\", \"to\", or both; integers 0-100\n• duration: {\"from\": 0, \"to\": 3600} — supports \"from\", \"to\", or both; values in SECONDS\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"]}}]}