skills.rest
operately
operatelyOFFICIAL
Explore all skills by this author →
Website𝕏@operatelyGitHub

mcp-tools

Guides creating and reviewing Operately MCP tools as API-first wrappers in Elixir.

553|70|Updated Feb 28, 2023
Search Tags:#testing#mcp#elixir#phoenix#api wrapper#tool catalog#oauth scopes
One-click install
npx skills add https://github.com/operately/operately --skill mcp-tools-operately
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: mcp-tools
Source: https://github.com/operately/operately/tree/main/.agents/skills/mcp-tools
Command: npx skills add https://github.com/operately/operately --skill mcp-tools-operately

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Exposing new Operately capabilities to ChatGPT or Claude MCP clients requires coordinating API handlers, MCP wrappers, OAuth scopes, and catalog tests across many files, and mistakes like duplicate tools or missing catalog entries fail CI. ## Core Features & Use Cases - API-first workflow: Enforces checking for existing MCP tools and API endpoints before writing code, and requires adding the API handler before the MCP wrapper. - Implementation contracts: Defines module structure, definition/0 fields, OAuth scopes (mcp:read/mcp:write), safety classifications, sort_order bands, and ID decoding conventions. - Two-layer testing: Prescribes exhaustive API tests with TurboCase plus MCP adaptation tests with ToolConnHelper, and mandatory @expected_tool_names catalog updates. - Use Case: When asked to expose a new Operately capability (e.g., listing task statuses) to MCP clients, follow the skill to add the API endpoint, register it, write the wrapper, and update the catalog test. ## Quick Start Ask the agent to add a new MCP tool for an Operately capability, and it will check for existing tools and API endpoints before generating the wrapper, tests, and catalog entry.

Frequently Asked Questions about mcp-tools

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I add a new MCP tool in Operately?▼

First check that no existing MCP tool or API endpoint covers the capability. If the API is missing, add the TurboConnect handler and register it in api.ex, then create the MCP wrapper under app/lib/operately_web/mcp/tools/, add both test layers, and update @expected_tool_names in tools_test.exs.

What OAuth scopes do Operately MCP tools use?▼

Operately MCP tools use two scopes: mcp:read for read-only tools and mcp:write for all write and destructive tools. There is no separate destructive scope; destructive tools stay on mcp:write with destructiveHint set in annotations.

Can an MCP tool call Operately context modules directly?▼

No. MCP tools must call OperatelyWeb.Api.* or OperatelyWeb.Api.Wrappers.* modules, never Operately.* context modules directly. The API layer is the source of truth for auth, permissions, business logic, and serialization.

Why does the MCP catalog test fail after adding a tool?▼

The catalog test fails when the new tool name is missing from @expected_tool_names in app/test/operately/mcp/tools_test.exs or is inserted at the wrong position. Entries must be sorted by sort_order, then alphabetically by name as a tiebreaker.

How are MCP tool tests different from API tests?▼

API tests use TurboCase and exhaustively cover auth, validation, and permissions over HTTP. MCP tests use Operately.DataCase with ToolConnHelper to call ToolModule.call/2 directly, focusing on ID decoding, cross-company not_found behavior, and optional-field handling.

Related Skills

Explore More Software Engineering Skills→
vtgiang-dotcomvtgiang-dotcom
3

api-patterns

Define REST and GraphQL APIs with consistent contracts and validation.

Community
Advanced
Happy-Technologies-LLCHappy-Technologies-LLC
34

mcp-server

Expose ServiceNow capabilities to AI agents via the MCP standard.

Official
Advanced
jamesaphoenixjamesaphoenix
1

verify-invariants

Link tests and source annotations to verify design invariants via tx spec.

Community
Advanced
hashgraphhashgraph
10

hedera

Direct AI agents to current Hedera documentation and official resources.

Official
Basic