@piagent/platform 1.2.15 → 1.2.17

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (75) hide show
  1. package/CHANGELOG.md +25 -0
  2. package/README.md +3 -3
  3. package/docs/README.md +1 -1
  4. package/docs/command-reference-vietnamese.md +2 -2
  5. package/docs/distribution-standard.md +7 -7
  6. package/docs/model-options.md +1 -1
  7. package/docs/operator-manual-vietnamese.md +7 -7
  8. package/docs/release-install-policy.md +6 -6
  9. package/docs/security-threat-model.md +1 -1
  10. package/docs/team-onboarding.md +2 -2
  11. package/docs/vercel-docs-site.md +7 -5
  12. package/docs-site/architecture.html +12 -6
  13. package/docs-site/assets/docs.css +52 -1
  14. package/docs-site/assets/docs.js +4 -2
  15. package/docs-site/benchmark.html +12 -6
  16. package/docs-site/commands.html +12 -6
  17. package/docs-site/content/en/architecture.html +33 -0
  18. package/docs-site/content/en/benchmark.html +164 -0
  19. package/docs-site/content/en/commands.html +39 -0
  20. package/docs-site/content/en/context-engine.html +30 -0
  21. package/docs-site/content/en/index.html +85 -0
  22. package/docs-site/content/en/mcp-approval.html +74 -0
  23. package/docs-site/content/en/mcp-auth.html +57 -0
  24. package/docs-site/content/en/mcp-servers.html +91 -0
  25. package/docs-site/content/en/mcp.html +90 -0
  26. package/docs-site/content/en/permissions.html +19 -0
  27. package/docs-site/content/en/profiles.html +27 -0
  28. package/docs-site/content/en/quickstart.html +126 -0
  29. package/docs-site/content/en/runtime.html +27 -0
  30. package/docs-site/content/en/scope.html +45 -0
  31. package/docs-site/content/en/security.html +33 -0
  32. package/docs-site/content/en/team.html +14 -0
  33. package/docs-site/content/en/workflows.html +21 -0
  34. package/docs-site/content/quickstart.html +1 -1
  35. package/docs-site/context-engine.html +12 -6
  36. package/docs-site/en/architecture.html +166 -0
  37. package/docs-site/en/benchmark.html +297 -0
  38. package/docs-site/en/commands.html +172 -0
  39. package/docs-site/en/context-engine.html +163 -0
  40. package/docs-site/en/index.html +203 -0
  41. package/docs-site/en/mcp-approval.html +207 -0
  42. package/docs-site/en/mcp-auth.html +190 -0
  43. package/docs-site/en/mcp-servers.html +224 -0
  44. package/docs-site/en/mcp.html +223 -0
  45. package/docs-site/en/permissions.html +152 -0
  46. package/docs-site/en/profiles.html +160 -0
  47. package/docs-site/en/quickstart.html +259 -0
  48. package/docs-site/en/runtime.html +160 -0
  49. package/docs-site/en/scope.html +178 -0
  50. package/docs-site/en/security.html +166 -0
  51. package/docs-site/en/team.html +143 -0
  52. package/docs-site/en/workflows.html +154 -0
  53. package/docs-site/index.html +12 -6
  54. package/docs-site/mcp-approval.html +12 -6
  55. package/docs-site/mcp-auth.html +12 -6
  56. package/docs-site/mcp-servers.html +12 -6
  57. package/docs-site/mcp.html +12 -6
  58. package/docs-site/permissions.html +12 -6
  59. package/docs-site/profiles.html +12 -6
  60. package/docs-site/quickstart.html +13 -7
  61. package/docs-site/runtime.html +12 -6
  62. package/docs-site/scope.html +12 -6
  63. package/docs-site/security.html +12 -6
  64. package/docs-site/team.html +12 -6
  65. package/docs-site/workflows.html +12 -6
  66. package/package.json +1 -1
  67. package/packages/piagent-core/package.json +1 -1
  68. package/scripts/build-docs-site.mjs +224 -50
  69. package/scripts/configure-model-scope.sh +4 -4
  70. package/scripts/install-global.sh +1 -1
  71. package/scripts/setup.sh +2 -2
  72. package/scripts/verify-local.sh +7 -1
  73. package/scripts/verify-release-identity.mjs +15 -6
  74. package/templates/global/settings.json +2 -2
  75. package/templates/project/.pi/settings.json +1 -1
package/docs-site/en/mcp-approval.html ADDED
@@ -0,0 +1,207 @@
1
+ <!doctype html>
2
+ <html lang="en" data-copy-success="Copied" data-copy-fallback="Select command">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>Repository servers require approval · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="Cloning an untrusted repository must not grant its author a process on the operator's machine. Decisions live outside the repository and are pinned by digest." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/en/mcp-approval" />
10
+ <link rel="alternate" hreflang="vi" href="https://piagent.io.vn/mcp-approval" />
11
+ <link rel="alternate" hreflang="en" href="https://piagent.io.vn/en/mcp-approval" />
12
+ <link rel="alternate" hreflang="x-default" href="https://piagent.io.vn/mcp-approval" />
13
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
14
+ <meta property="og:title" content="Repository servers require approval · Pi Agent Platform Docs" />
15
+ <meta property="og:description" content="Cloning an untrusted repository must not grant its author a process on the operator's machine. Decisions live outside the repository and are pinned by digest." />
16
+ <meta property="og:url" content="https://piagent.io.vn/en/mcp-approval" />
17
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
18
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
19
+ <link
20
+ href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
21
+ rel="stylesheet"
22
+ />
23
+ <link rel="stylesheet" href="/assets/docs.css" />
24
+ <script src="/assets/docs.js" defer></script>
25
+ </head>
26
+ <body>
27
+ <header class="topbar">
28
+ <a class="brand" href="/en/" aria-label="Pi Agent Platform">
29
+ <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
30
+ <span>Pi Agent Platform</span>
31
+ </a>
32
+ <div class="top-actions">
33
+ <span class="pill"><span class="pill-dot"></span>v1.2.17 docs · EN</span>
34
+ <nav class="language-switch" aria-label="Language">
35
+ <a class="language-option" href="/mcp-approval" hreflang="vi" lang="vi">VI</a>
36
+ <a class="language-option current" href="/en/mcp-approval" hreflang="en" lang="en" aria-current="true">EN</a>
37
+ </nav>
38
+ <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Open GitHub repository">
39
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
40
+ <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
41
+ </svg>
42
+ GitHub
43
+ </a>
44
+ <button class="button mobile-menu" type="button" data-menu>Menu</button>
45
+ <a class="button top-command-link" href="/en/commands">Commands</a>
46
+ </div>
47
+ </header>
48
+
49
+ <div class="layout with-toc">
50
+ <aside class="sidebar" data-sidebar>
51
+ <div class="sidebar-search" aria-label="Search documentation">
52
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
53
+ <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
54
+ </svg>
55
+ <input type="search" placeholder="Search pages" data-filter />
56
+ </div>
57
+
58
+ <nav aria-label="Documentation">
59
+ <div class="nav-group">
60
+ <p class="nav-title">Get started</p>
61
+ <a class="nav-link" href="/en/">Overview</a>
62
+ <a class="nav-link" href="/en/quickstart">Quickstart</a>
63
+ <a class="nav-link" href="/en/scope">Platform scope</a>
64
+ </div>
65
+ <div class="nav-group">
66
+ <p class="nav-title">Build</p>
67
+ <a class="nav-link" href="/en/profiles">Project profiles</a>
68
+ <a class="nav-link" href="/en/permissions">Permission modes</a>
69
+ <a class="nav-link" href="/en/commands">Command catalog</a>
70
+ <a class="nav-link" href="/en/workflows">Workflows</a>
71
+ </div>
72
+ <div class="nav-group">
73
+ <p class="nav-title">MCP</p>
74
+ <a class="nav-link" href="/en/mcp">MCP overview</a>
75
+ <a class="nav-link" href="/en/mcp-servers">Server management</a>
76
+ <a class="nav-link" href="/en/mcp-auth">Authentication</a>
77
+ <a class="nav-link current" href="/en/mcp-approval" aria-current="page">Approval gate</a>
78
+ </div>
79
+ <div class="nav-group">
80
+ <p class="nav-title">Operate</p>
81
+ <a class="nav-link" href="/en/security">Security model</a>
82
+ <a class="nav-link" href="/en/architecture">Architecture</a>
83
+ <a class="nav-link" href="/en/context-engine">Context Engine</a>
84
+ <a class="nav-link" href="/en/benchmark">Benchmark</a>
85
+ <a class="nav-link" href="/en/runtime">Runtime tools</a>
86
+ <a class="nav-link" href="/en/team">Team usage</a>
87
+ </div>
88
+ </nav>
89
+ </aside>
90
+
91
+ <main>
92
+ <div class="content-shell" data-article>
93
+ <nav class="breadcrumb" aria-label="Breadcrumb">
94
+ <a href="/en/">Docs</a>
95
+ <span aria-hidden="true">/</span>
96
+ <span>MCP</span>
97
+ <span aria-hidden="true">/</span>
98
+ <span>Approval gate</span>
99
+ </nav>
100
+ <div class="page-head">
101
+ <h1>Repository servers require approval</h1>
102
+ <p>Cloning an untrusted repository must not grant its author a process on the operator's machine. Decisions live outside the repository and are pinned by digest.</p>
103
+ </div>
104
+ <section class="section">
105
+ <h2 id="problem">The problem</h2>
106
+ <p>A repository may include <span class="inline-code">.mcp.json</span> and <span class="inline-code">.pi/mcp.json</span>. Cloning an untrusted repository and opening a session must <strong>not</strong> grant its author a process on the operator's machine with the operator's credentials. Servers from those scopes remain unavailable until someone on the machine approves them.</p>
107
+ <pre><code>/piagent-mcp get internal # inspect first
108
+ /piagent-mcp approve internal # or reject, or reset</code></pre>
109
+ <p>In a terminal, omit the slash: <span class="inline-code">piagent-mcp get internal</span>. Both surfaces store the same decision in the same file.</p>
110
+ <p><span class="inline-code">approve</span> prints the definition before recording consent. Approving without reading is exactly what this gate is designed to prevent.</p>
111
+ </section>
112
+
113
+ <section class="section">
114
+ <h2 id="three-properties">Three properties</h2>
115
+ <div class="grid">
116
+ <div class="card"><h3 id="outside-repository">The decision lives outside the repository</h3><p>It is stored in <span class="inline-code">~/.pi/piagent-mcp-approvals.json</span>. If a repository could approve itself, the gate would not exist. A fork, rename, or second checkout starts at <span class="inline-code">pending</span>.</p></div>
117
+ <div class="card"><h3 id="digest-pinning">Pinned by digest</h3><p>Approval means consenting to <em>what the server runs</em>. Changing the command, URL, or arguments creates a new decision and returns the state to <span class="inline-code">approval-changed</span>.</p></div>
118
+ <div class="card"><h3 id="tool-call-enforcement">Enforced at tool call</h3><p>The guard handles both the proxy form (<span class="inline-code">mcp</span> with <span class="inline-code">input.server</span>) and direct tools. A proxy-only gate could be bypassed by enabling <span class="inline-code">directTools</span>.</p></div>
119
+ </div>
120
+ </section>
121
+
122
+ <section class="section">
123
+ <h2 id="limit">Limit</h2>
124
+ <div class="callout">
125
+ <strong>The gate cannot prevent connection establishment</strong>
126
+ <p>The adapter owns connections, so the extension cannot stop one from opening. It blocks <strong>every tool call</strong>, not the connection itself. The residual risk is the connection and any remote log that records it.</p>
127
+ </div>
128
+ <p>Servers in <span class="inline-code">global</span> and <span class="inline-code">pi-global</span> do not pass through this gate. A repository cannot place a server in those scopes, and asking users to approve their own machine configuration would add no security value.</p>
129
+ </section>
130
+
131
+ <section class="section">
132
+ <h2 id="imports">Servers supplied through <span class="inline-code">imports</span></h2>
133
+ <p>MCP configuration supports an <span class="inline-code">imports</span> key that reads server definitions from other tools. Imported servers are not directly declared in one of the four scopes, which creates another path around a naive approval gate.</p>
134
+ <p>Of the six import kinds, only <span class="inline-code">vscode</span> points to a path <strong>inside the project</strong>: <span class="inline-code">.vscode/mcp.json</span>. It travels with a clone and requires approval like any directly declared repository server.</p>
135
+ <div class="table-wrap">
136
+ <table>
137
+ <thead><tr><th>Situation</th><th>Handling</th></tr></thead>
138
+ <tbody>
139
+ <tr><td>Any layer imports a repository-relative kind</td><td>The server requires approval even when the import is declared globally, because the loaded content still lives in the repository.</td></tr>
140
+ <tr><td>A repository scope imports any kind</td><td>The server requires approval because the repository selected what the machine should run.</td></tr>
141
+ <tr><td>A repository scope imports a format that cannot be read, such as Codex TOML</td><td>Block every tool call when that file exists. A present but unreadable source is not equivalent to an empty configuration.</td></tr>
142
+ <tr><td><span class="inline-code">remove</span>, <span class="inline-code">enable</span>, or <span class="inline-code">disable</span> targets an imported server</td><td>Reject the operation and name the actual file to edit. Rewriting another tool's configuration with the platform writer would corrupt ownership and format.</td></tr>
143
+ <tr><td>Repository configuration combines <span class="inline-code">directTools</span> with <span class="inline-code">toolPrefix: "none"</span></td><td>Block every tool call. Without a prefix, the server identity cannot be recovered for approval lookup, while blocking only the proxy would let the unprefixed direct tools pass.</td></tr>
144
+ </tbody>
145
+ </table>
146
+ </div>
147
+ <p><span class="inline-code">piagent-mcp doctor</span> names the importing file, its import kinds, unreadable layers, and import targets that exist but cannot be read. These states must not collapse into "no servers declared".</p>
148
+ <p>For full-block states, <span class="inline-code">doctor</span> and <span class="inline-code">list</span> explain the reason and exit 1, including <span class="inline-code">list --json</span>. Exit status answers whether MCP can operate, not whether the command printed rows. The guard, slash command, and CLI consume the same state.</p>
149
+ <p>The gate cache is scoped by project and recomputed when the signature of every file used by readers changes, including currently missing paths. This lets a newly created imported file or a personal global change become visible immediately.</p>
150
+ <p>The adapter merges <span class="inline-code">settings</span> across all four layers for the session. Therefore <span class="inline-code">directTools</span> in one file and <span class="inline-code">toolPrefix: "none"</span> in another still form the unsafe combination. The report identifies both files.</p>
151
+ <p>The <span class="inline-code">SCOPE</span> column names the layer that declared <span class="inline-code">imports</span>, not the location that defined the server. A server imported by global configuration may still require approval when its source is in the clone.</p>
152
+ </section>
153
+
154
+ <section class="section">
155
+ <h2 id="design-decisions">Design decisions</h2>
156
+ <div class="table-wrap">
157
+ <table>
158
+ <thead><tr><th>Decision</th><th>Reason</th></tr></thead>
159
+ <tbody>
160
+ <tr><td>Gate repository-supplied servers only</td><td>Only <span class="inline-code">.mcp.json</span> and <span class="inline-code">.pi/mcp.json</span> travel with a clone. User-owned machine configuration needs no repository consent.</td></tr>
161
+ <tr><td>Store decisions outside the repository</td><td><span class="inline-code">~/.pi/piagent-mcp-approvals.json</span> prevents a repository from approving itself.</td></tr>
162
+ <tr><td>Pin the definition digest</td><td>Consent applies to the exact command, arguments, and URL. A change returns the server to pending.</td></tr>
163
+ <tr><td>Preview the merged definition but hash the repository-owned fragment</td><td>The adapter merges duplicate IDs by key, so preview must show what will run. Hashing only the repository-controlled fragment prevents unrelated global edits from invalidating consent.</td></tr>
164
+ <tr><td>Block at <span class="inline-code">tool_call</span></td><td>Cover both proxy and direct tools without a bypass. Direct tools are traced through their configured server prefix.</td></tr>
165
+ </tbody>
166
+ </table>
167
+ </div>
168
+ <p>The ideal point would be before connection, but that requires owning the connection. Piagent chooses the furthest point it actually controls and states the residual risk explicitly.</p>
169
+ </section>
170
+
171
+ <section class="section">
172
+ <h2 id="migration">Migration</h2>
173
+ <div class="callout">
174
+ <strong>Projects with existing servers</strong>
175
+ <p>Servers already present in <span class="inline-code">.mcp.json</span> or <span class="inline-code">.pi/mcp.json</span> become <span class="inline-code">pending-approval</span> after update. Run <span class="inline-code">/piagent-mcp approve &lt;name&gt;</span> once per project. Shipped templates are empty, so most projects are unaffected; session notices and doctor name every server requiring review.</p>
176
+ </div>
177
+ </section>
178
+ <nav class="pager" aria-label="Adjacent pages">
179
+ <a class="pager-prev" href="/en/mcp-auth">
180
+ <span class="pager-label">Previous</span>
181
+ <span class="pager-title">Authentication</span>
182
+ </a>
183
+ <a class="pager-next" href="/en/security">
184
+ <span class="pager-label">Next</span>
185
+ <span class="pager-title">Security model</span>
186
+ </a>
187
+ </nav>
188
+
189
+ <footer class="footer">
190
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
191
+ <div class="footer-links" aria-label="External links">
192
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
193
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
194
+ <a href="/mcp-approval" hreflang="vi">Tiếng Việt</a>
195
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
196
+ </div>
197
+ </footer>
198
+ </div>
199
+ </main>
200
+
201
+ <aside class="toc" aria-label="Page contents">
202
+ <p class="toc-title">On this page</p>
203
+ <nav data-toc></nav>
204
+ </aside>
205
+ </div>
206
+ </body>
207
+ </html>
package/docs-site/en/mcp-auth.html ADDED
@@ -0,0 +1,190 @@
1
+ <!doctype html>
2
+ <html lang="en" data-copy-success="Copied" data-copy-fallback="Select command">
3
+ <head>
4
+ <meta charset="utf-8" />
5
+ <meta name="viewport" content="width=device-width, initial-scale=1" />
6
+ <title>Authentication and readiness · Pi Agent Platform Docs</title>
7
+ <meta name="description" content="The platform does not store tokens or run OAuth. It rejects secrets in configuration and reports which servers are actually ready." />
8
+ <meta name="theme-color" content="#050505" />
9
+ <link rel="canonical" href="https://piagent.io.vn/en/mcp-auth" />
10
+ <link rel="alternate" hreflang="vi" href="https://piagent.io.vn/mcp-auth" />
11
+ <link rel="alternate" hreflang="en" href="https://piagent.io.vn/en/mcp-auth" />
12
+ <link rel="alternate" hreflang="x-default" href="https://piagent.io.vn/mcp-auth" />
13
+ <link rel="icon" href="/favicon.svg" type="image/svg+xml" />
14
+ <meta property="og:title" content="Authentication and readiness · Pi Agent Platform Docs" />
15
+ <meta property="og:description" content="The platform does not store tokens or run OAuth. It rejects secrets in configuration and reports which servers are actually ready." />
16
+ <meta property="og:url" content="https://piagent.io.vn/en/mcp-auth" />
17
+ <link rel="preconnect" href="https://fonts.googleapis.com" />
18
+ <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
19
+ <link
20
+ href="https://fonts.googleapis.com/css2?family=Be+Vietnam+Pro:wght@400;500;600;700;800&family=JetBrains+Mono:wght@400;500;600&display=swap"
21
+ rel="stylesheet"
22
+ />
23
+ <link rel="stylesheet" href="/assets/docs.css" />
24
+ <script src="/assets/docs.js" defer></script>
25
+ </head>
26
+ <body>
27
+ <header class="topbar">
28
+ <a class="brand" href="/en/" aria-label="Pi Agent Platform">
29
+ <span class="brand-mark"><img src="/assets/piagent-logo.svg" alt="" /></span>
30
+ <span>Pi Agent Platform</span>
31
+ </a>
32
+ <div class="top-actions">
33
+ <span class="pill"><span class="pill-dot"></span>v1.2.17 docs · EN</span>
34
+ <nav class="language-switch" aria-label="Language">
35
+ <a class="language-option" href="/mcp-auth" hreflang="vi" lang="vi">VI</a>
36
+ <a class="language-option current" href="/en/mcp-auth" hreflang="en" lang="en" aria-current="true">EN</a>
37
+ </nav>
38
+ <a class="button social" href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer" aria-label="Open GitHub repository">
39
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
40
+ <path d="M7 17 17 7M9 7h8v8" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" />
41
+ </svg>
42
+ GitHub
43
+ </a>
44
+ <button class="button mobile-menu" type="button" data-menu>Menu</button>
45
+ <a class="button top-command-link" href="/en/commands">Commands</a>
46
+ </div>
47
+ </header>
48
+
49
+ <div class="layout with-toc">
50
+ <aside class="sidebar" data-sidebar>
51
+ <div class="sidebar-search" aria-label="Search documentation">
52
+ <svg viewBox="0 0 24 24" fill="none" aria-hidden="true">
53
+ <path d="M10.8 18.1a7.3 7.3 0 1 1 0-14.6 7.3 7.3 0 0 1 0 14.6Zm5.3-1.7 4.4 4.4" stroke="currentColor" stroke-width="2" stroke-linecap="round" />
54
+ </svg>
55
+ <input type="search" placeholder="Search pages" data-filter />
56
+ </div>
57
+
58
+ <nav aria-label="Documentation">
59
+ <div class="nav-group">
60
+ <p class="nav-title">Get started</p>
61
+ <a class="nav-link" href="/en/">Overview</a>
62
+ <a class="nav-link" href="/en/quickstart">Quickstart</a>
63
+ <a class="nav-link" href="/en/scope">Platform scope</a>
64
+ </div>
65
+ <div class="nav-group">
66
+ <p class="nav-title">Build</p>
67
+ <a class="nav-link" href="/en/profiles">Project profiles</a>
68
+ <a class="nav-link" href="/en/permissions">Permission modes</a>
69
+ <a class="nav-link" href="/en/commands">Command catalog</a>
70
+ <a class="nav-link" href="/en/workflows">Workflows</a>
71
+ </div>
72
+ <div class="nav-group">
73
+ <p class="nav-title">MCP</p>
74
+ <a class="nav-link" href="/en/mcp">MCP overview</a>
75
+ <a class="nav-link" href="/en/mcp-servers">Server management</a>
76
+ <a class="nav-link current" href="/en/mcp-auth" aria-current="page">Authentication</a>
77
+ <a class="nav-link" href="/en/mcp-approval">Approval gate</a>
78
+ </div>
79
+ <div class="nav-group">
80
+ <p class="nav-title">Operate</p>
81
+ <a class="nav-link" href="/en/security">Security model</a>
82
+ <a class="nav-link" href="/en/architecture">Architecture</a>
83
+ <a class="nav-link" href="/en/context-engine">Context Engine</a>
84
+ <a class="nav-link" href="/en/benchmark">Benchmark</a>
85
+ <a class="nav-link" href="/en/runtime">Runtime tools</a>
86
+ <a class="nav-link" href="/en/team">Team usage</a>
87
+ </div>
88
+ </nav>
89
+ </aside>
90
+
91
+ <main>
92
+ <div class="content-shell" data-article>
93
+ <nav class="breadcrumb" aria-label="Breadcrumb">
94
+ <a href="/en/">Docs</a>
95
+ <span aria-hidden="true">/</span>
96
+ <span>MCP</span>
97
+ <span aria-hidden="true">/</span>
98
+ <span>Authentication</span>
99
+ </nav>
100
+ <div class="page-head">
101
+ <h1>Authentication and readiness</h1>
102
+ <p>The platform does not store tokens or run OAuth. It rejects secrets in configuration and reports which servers are actually ready.</p>
103
+ </div>
104
+ <section class="section">
105
+ <h2 id="no-token-storage">The platform does not store tokens</h2>
106
+ <p>MCP tokens already have an owner: OAuth belongs to <span class="inline-code">pi-mcp-adapter</span>. The adapter registers <span class="inline-code">/mcp</span> and <span class="inline-code">/mcp-auth</span> and owns storage, refresh, and revocation. A second credential store would only create another leak surface. The platform therefore <strong>detects and guides</strong>.</p>
107
+ <pre><code>/mcp-auth figma</code></pre>
108
+ <div class="callout ok-callout">
109
+ <strong>Boundary</strong>
110
+ <p>The platform does not execute OAuth, store tokens, or refresh them. It can identify that a server <em>requires</em> authentication, but cannot prove whether an existing login is still valid, and reports that uncertainty explicitly.</p>
111
+ </div>
112
+ </section>
113
+
114
+ <section class="section">
115
+ <h2 id="reject-secrets">Secrets are rejected before configuration is written</h2>
116
+ <p>MCP configuration may be read by several clients, lives in a home directory or repository, and project scope may be committed. A token supplied through <span class="inline-code">--env</span> would propagate to all those locations. The add command rejects it and shows the safe form:</p>
117
+ <pre><code>$ piagent-mcp add gh --env GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx -- npx -y @acme/gh-mcp
118
+ FAIL: GITHUB_PERSONAL_ACCESS_TOKEN names a credential, so its value cannot be
119
+ written into MCP config. Export it in your shell and reference it instead:
120
+ --env 'GITHUB_PERSONAL_ACCESS_TOKEN=${GITHUB_PERSONAL_ACCESS_TOKEN}'</code></pre>
121
+ <div class="split">
122
+ <div class="card"><h3 id="field-name">Field-name detection</h3><p>Names containing <span class="inline-code">token</span>, <span class="inline-code">secret</span>, <span class="inline-code">password</span>, <span class="inline-code">api_key</span>, or <span class="inline-code">authorization</span> require environment-variable references.</p></div>
123
+ <div class="card"><h3 id="value-shape">Value-shape detection</h3><p>Values are checked independently, so a neutral name such as <span class="inline-code">--env CONFIG=ghp_...</span> is also rejected.</p></div>
124
+ </div>
125
+ <p>The same rules apply to <span class="inline-code">--header</span>. <span class="inline-code">--url</span> accepts HTTPS, or HTTP only for loopback hosts such as Figma desktop MCP. <span class="inline-code">list</span> and <span class="inline-code">get</span> mask values while preserving <span class="inline-code">${VAR}</span>, because the variable name is not the credential.</p>
126
+ </section>
127
+
128
+ <section class="section">
129
+ <h2 id="readiness">Readiness states</h2>
130
+ <p>A server count cannot show which server can answer a call. <span class="inline-code">/piagent-mcp doctor</span> classifies each server:</p>
131
+ <div class="table-wrap">
132
+ <table>
133
+ <thead><tr><th>State</th><th>Meaning</th><th>Action</th></tr></thead>
134
+ <tbody>
135
+ <tr><td><span class="inline-code">ready</span></td><td>Requirements are satisfied</td><td>—</td></tr>
136
+ <tr><td><span class="inline-code">needs-env</span></td><td>Configuration references an unset <span class="inline-code">${VAR}</span></td><td>Export the variable in the shell profile</td></tr>
137
+ <tr><td><span class="inline-code">needs-command</span></td><td>The executable is missing from PATH</td><td>Install it or update the server definition</td></tr>
138
+ <tr><td><span class="inline-code">pending-approval</span></td><td>The repository supplied this server and the machine has not approved it</td><td><span class="inline-code">/piagent-mcp approve &lt;name&gt;</span></td></tr>
139
+ <tr><td><span class="inline-code">approval-changed</span></td><td>An approved definition changed</td><td>Review and approve again</td></tr>
140
+ <tr><td><span class="inline-code">rejected</span></td><td>The project server was rejected</td><td>Use <span class="inline-code">reset</span> to reconsider</td></tr>
141
+ <tr><td><span class="inline-code">disabled</span></td><td>Disabled explicitly</td><td><span class="inline-code">/piagent-mcp enable &lt;name&gt;</span></td></tr>
142
+ <tr><td><span class="inline-code">oauth</span></td><td>Authentication is owned by Pi</td><td><span class="inline-code">/mcp-auth &lt;name&gt;</span> when login is needed</td></tr>
143
+ </tbody>
144
+ </table>
145
+ </div>
146
+ <p>The report states only what it can prove. <span class="inline-code">needs-env</span> prints the variable <strong>name</strong>, never its value.</p>
147
+ <p>Inside a session, <span class="inline-code">/piagent-mcp doctor</span> returns the same report with slash-command remedies. From a terminal:</p>
148
+ <pre><code>$ piagent-mcp doctor
149
+ OK context7 (global): ready
150
+ OK chrome-devtools (global): ready
151
+ NEED github (global): GITHUB_PERSONAL_ACCESS_TOKEN is referenced but not set
152
+ -> export GITHUB_PERSONAL_ACCESS_TOKEN=... in your shell profile
153
+ NEED docker: installed but the daemon is not responding
154
+ -> start Docker Desktop, then re-run piagent-mcp doctor</code></pre>
155
+ <div class="callout">
156
+ <strong>Why <span class="inline-code">oauth</span> is not an error</strong>
157
+ <p>It does not appear in the session-start notice because the platform cannot tell whether the user is already logged in. Repeating an uncertain warning every session would create noise. The notice includes only proven blockers; disable it with <span class="inline-code">PIAGENT_NO_MCP_NOTICE=1</span>.</p>
158
+ </div>
159
+ <p><span class="inline-code">doctor</span> also runs <span class="inline-code">docker info</span>. That slower check belongs in doctor, not session startup. <span class="inline-code">piagent-doctor</span> includes blocking states in its warnings.</p>
160
+ </section>
161
+ <nav class="pager" aria-label="Adjacent pages">
162
+ <a class="pager-prev" href="/en/mcp-servers">
163
+ <span class="pager-label">Previous</span>
164
+ <span class="pager-title">Server management</span>
165
+ </a>
166
+ <a class="pager-next" href="/en/mcp-approval">
167
+ <span class="pager-label">Next</span>
168
+ <span class="pager-title">Approval gate</span>
169
+ </a>
170
+ </nav>
171
+
172
+ <footer class="footer">
173
+ <p>Pi Agent Platform docs · static HTML · governed agent workflow</p>
174
+ <div class="footer-links" aria-label="External links">
175
+ <a href="https://piagent.io.vn" target="_blank" rel="noopener noreferrer">piagent.io.vn</a>
176
+ <a href="https://github.com/Vt-mmm/piagent" target="_blank" rel="noopener noreferrer">GitHub repository</a>
177
+ <a href="/mcp-auth" hreflang="vi">Tiếng Việt</a>
178
+ <a href="https://www.facebook.com/vinhtam0544/" target="_blank" rel="noopener noreferrer">Facebook profile</a>
179
+ </div>
180
+ </footer>
181
+ </div>
182
+ </main>
183
+
184
+ <aside class="toc" aria-label="Page contents">
185
+ <p class="toc-title">On this page</p>
186
+ <nav data-toc></nav>
187
+ </aside>
188
+ </div>
189
+ </body>
190
+ </html>